feat: add layout layout throttling and transitions

modules/graph-layers/src/core/graph-engine.ts

@@ -12,17 +12,28 @@ import {log} from '../utils/log';
 export type GraphEngineProps = {
   graph: Graph;
   layout: GraphLayout;
+  /**
+   * Throttle layout change notifications (in milliseconds). When greater than zero the
+   * engine will avoid emitting more than one `onLayoutChange` event within the configured
+   * interval. This is useful to slow down very fast layout updates so that the
+   * visualization can animate at a comfortable pace.
+   */
+  layoutUpdateThrottleMs?: number;
 };
 
 /** Graph engine controls the graph data and layout calculation */
 export class GraphEngine extends EventTarget {
-  props: Readonly<Required<GraphEngineProps>>;
+  props: Readonly<GraphEngineProps>;
 
   private readonly _graph: Graph;
   private readonly _layout: GraphLayout;
+  private readonly _layoutUpdateThrottleMs: number;
   private readonly _cache = new Cache<'nodes' | 'edges', Node[] | Edge[]>();
   private _layoutDirty = false;
   private _transactionInProgress = false;
+  private _layoutChangeTimeout: ReturnType<typeof setTimeout> | null = null;
+  private _lastLayoutChangeTs = 0;
+  private _pendingLayoutChange = false;
 
   constructor(props: GraphEngineProps);
   /** @deprecated Use props constructor: new GraphEngine(props) */
@@ -40,6 +51,7 @@ export class GraphEngine extends EventTarget {
     this.props = props;
     this._graph = props.graph;
     this._layout = props.layout;
+    this._layoutUpdateThrottleMs = props.layoutUpdateThrottleMs ?? 0;
   }
 
   /** Getters */
@@ -91,7 +103,7 @@ export class GraphEngine extends EventTarget {
   /**
    * @fires GraphEngine#onLayoutChange
    */
-  _onLayoutChange = () => {
+  private _emitLayoutChangeEvent = () => {
     log.log(0, 'GraphEngine: layout update event')();
     /**
      * @event GraphEngine#onLayoutChange
@@ -100,10 +112,66 @@ export class GraphEngine extends EventTarget {
     this.dispatchEvent(new CustomEvent('onLayoutChange'));
   };
 
+  private _clearPendingLayoutChange() {
+    if (this._layoutChangeTimeout) {
+      clearTimeout(this._layoutChangeTimeout);
+      this._layoutChangeTimeout = null;
+    }
+    this._pendingLayoutChange = false;
+  }
+
+  private _handleLayoutChange = () => {
+    if (!this._layoutUpdateThrottleMs) {
+      this._clearPendingLayoutChange();
+      this._lastLayoutChangeTs = Date.now();
+      this._emitLayoutChangeEvent();
+      return;
+    }
+
+    const now = Date.now();
+    const elapsed = now - this._lastLayoutChangeTs;
+    if (!this._layoutChangeTimeout) {
+      if (elapsed >= this._layoutUpdateThrottleMs) {
+        this._lastLayoutChangeTs = now;
+        this._emitLayoutChangeEvent();
+        return;
+      }
+
+      const delay = Math.max(this._layoutUpdateThrottleMs - elapsed, 0);
+      this._scheduleThrottledLayoutChange(delay);
+      return;
+    }
+
+    this._pendingLayoutChange = true;
+  };
+
+  private _scheduleThrottledLayoutChange(delay: number) {
+    this._layoutChangeTimeout = setTimeout(() => {
+      this._layoutChangeTimeout = null;
+      this._lastLayoutChangeTs = Date.now();
+      this._emitLayoutChangeEvent();
+      if (this._pendingLayoutChange) {
+        this._pendingLayoutChange = false;
+        if (this._layoutUpdateThrottleMs > 0) {
+          this._scheduleThrottledLayoutChange(this._layoutUpdateThrottleMs);
+        }
+      }
+    }, delay);
+  }
+
+  _onLayoutChange = () => {
+    this._handleLayoutChange();
+  };
+
   /**
    * @fires GraphEngine#onLayoutDone
    */
   _onLayoutDone = () => {
+    if (this._layoutUpdateThrottleMs && this._layoutChangeTimeout) {
+      this._clearPendingLayoutChange();
+      this._lastLayoutChangeTs = Date.now();
+      this._emitLayoutChangeEvent();
+    }
     log.log(0, 'GraphEngine: layout end')();
     /**
      * @event GraphEngine#onLayoutDone
@@ -142,6 +210,8 @@ export class GraphEngine extends EventTarget {
   run = () => {
     log.log(1, 'GraphEngine: run')();
     // TODO: throw if running on a cleared engine
+    this._clearPendingLayoutChange();
+    this._lastLayoutChangeTs = 0;
 
     this._graph.addEventListener('transactionStart', this._onTransactionStart);
     this._graph.addEventListener('transactionEnd', this._onTransactionEnd);
@@ -172,6 +242,8 @@ export class GraphEngine extends EventTarget {
     this._layout.removeEventListener('onLayoutChange', this._onLayoutChange);
     this._layout.removeEventListener('onLayoutDone', this._onLayoutDone);
     this._layout.removeEventListener('onLayoutError', this._onLayoutError);
+
+    this._clearPendingLayoutChange();
   };
 
   resume = () => this._layout.resume();
@@ -186,6 +258,7 @@ export class GraphEngine extends EventTarget {
 
   _updateLayout = () => {
     log.log(0, 'GraphEngine: layout update')();
+    this._lastLayoutChangeTs = 0;
     this._layout.updateGraph(this._graph);
     this._layout.update();
     this._layoutDirty = false;

modules/graph-layers/src/layers/edge-layer.ts

@@ -55,7 +55,8 @@ export class EdgeLayer extends CompositeLayer {
   }
 
   renderLayers() {
-    const {getLayoutInfo, pickable, positionUpdateTrigger, stylesheet, id} = this.props as any;
+    const {getLayoutInfo, pickable, positionUpdateTrigger, stylesheet, id, transitions} =
+      this.props as any;
 
     const {typedEdgeData} = this.state;
 
@@ -67,21 +68,24 @@ export class EdgeLayer extends CompositeLayer {
       if (!Layer) {
         return null;
       }
-      return new Layer({
-        id: `${id}-${idx}`,
-        data: edgeData,
-        getLayoutInfo,
-        getColor: stylesheet.getDeckGLAccessor('getColor'),
-        getWidth: stylesheet.getDeckGLAccessor('getWidth'),
-        colorUpdateTrigger: stylesheet.getDeckGLAccessorUpdateTrigger('getColor'),
-        widthUpdateTrigger: stylesheet.getDeckGLAccessorUpdateTrigger('getWidth'),
-        positionUpdateTrigger,
-        pickable,
-        coordinateSystem: COORDINATE_SYSTEM.CARTESIAN,
-        parameters: {
-          depthCompare: 'always'
-        }
-      } as any);
+      return new Layer(
+        this.getSubLayerProps({
+          id: `${id}-${idx}`,
+          data: edgeData,
+          getLayoutInfo,
+          getColor: stylesheet.getDeckGLAccessor('getColor'),
+          getWidth: stylesheet.getDeckGLAccessor('getWidth'),
+          colorUpdateTrigger: stylesheet.getDeckGLAccessorUpdateTrigger('getColor'),
+          widthUpdateTrigger: stylesheet.getDeckGLAccessorUpdateTrigger('getWidth'),
+          positionUpdateTrigger,
+          pickable,
+          transitions,
+          coordinateSystem: COORDINATE_SYSTEM.CARTESIAN,
+          parameters: {
+            depthCompare: 'always'
+          }
+        })
+      );
     });
   }
 }

modules/graph-layers/src/layers/edge-layers/edge-arrow-layer.ts

@@ -116,7 +116,8 @@ export class EdgeArrowLayer extends CompositeLayer {
   static layerName = 'EdgeArrowLayer';
 
   renderLayers() {
-    const {data, getLayoutInfo, positionUpdateTrigger = 0, stylesheet} = this.props as any;
+    const {data, getLayoutInfo, positionUpdateTrigger = 0, stylesheet, transitions} =
+      this.props as any;
     const directedEdges = (data || []).filter(isEdgeDirected);
 
     if (!directedEdges.length) {
@@ -154,6 +155,7 @@ export class EdgeArrowLayer extends CompositeLayer {
           parameters: {
             depthTest: false
           },
+          transitions,
           updateTriggers: {
             getColor: updateTriggers.getColor,
             getScale: updateTriggers.getSize,

modules/graph-layers/src/layers/edge-layers/edge-label-layer.ts

@@ -9,7 +9,8 @@ export class EdgeLabelLayer extends CompositeLayer {
   static layerName = 'EdgeLabelLayer';
 
   renderLayers() {
-    const {data, getLayoutInfo, positionUpdateTrigger = 0, stylesheet} = this.props as any;
+    const {data, getLayoutInfo, positionUpdateTrigger = 0, stylesheet, transitions} =
+      this.props as any;
     return [
       new ZoomableTextLayer(
         this.getSubLayerProps({
@@ -37,6 +38,7 @@ export class EdgeLabelLayer extends CompositeLayer {
             return (Math.atan2(deltaY, deltaX) * -180) / Math.PI;
           },
           ...stylesheet.getDeckGLAccessors(),
+          transitions,
           updateTriggers: {
             ...stylesheet.getDeckGLUpdateTriggers(),
             getPosition: positionUpdateTrigger

modules/graph-layers/src/layers/edge-layers/flow-layer.ts

@@ -10,7 +10,8 @@ export class FlowLayer extends CompositeLayer {
   static layerName = 'FlowLayer';
 
   renderLayers() {
-    const {data, getLayoutInfo, positionUpdateTrigger = 0, stylesheet} = this.props as any;
+    const {data, getLayoutInfo, positionUpdateTrigger = 0, stylesheet, transitions} =
+      this.props as any;
     return [
       new FlowPathLayer(
         this.getSubLayerProps({
@@ -22,6 +23,7 @@ export class FlowLayer extends CompositeLayer {
           parameters: {
             depthTest: false
           },
+          transitions,
           updateTriggers: {
             ...stylesheet.getDeckGLUpdateTriggers(),
             getSourcePosition: positionUpdateTrigger,