@deck.gl-community/graph-layers 9.2.0-beta.2 → 9.2.0-beta.3

package/src/core/graph-engine.ts

@@ -4,67 +4,125 @@
 
 import type {Bounds2D} from '@math.gl/types';
 
-import type {Node} from '../graph/node';
-import {Edge} from '../graph/edge';
-import {Graph} from '../graph/graph';
+import type {Graph, EdgeInterface, NodeInterface} from '../graph/graph';
+import {ClassicGraph} from '../graph/classic-graph';
 import {GraphLayout, type GraphLayoutEventDetail} from './graph-layout';
 import {Cache} from './cache';
 import {log} from '../utils/log';
+import {GraphStylesheetEngine, type GraphStylesheet} from '../style/graph-style-engine';
 
-export type GraphEngineProps = {
+type ClassicGraphEngineProps = {
+  graph: ClassicGraph;
+  layout: GraphLayout;
+  onLayoutStart?: (detail?: GraphLayoutEventDetail) => void;
+  onLayoutChange?: (detail?: GraphLayoutEventDetail) => void;
+  onLayoutDone?: (detail?: GraphLayoutEventDetail) => void;
+  onLayoutError?: (error?: unknown) => void;
+  onTransactionStart?: () => void;
+  onTransactionEnd?: () => void;
+  onNodeAdded?: (node: NodeInterface) => void;
+  onNodeRemoved?: (node: NodeInterface) => void;
+  onNodeUpdated?: (node: NodeInterface) => void;
+  onEdgeAdded?: (edge: EdgeInterface) => void;
+  onEdgeRemoved?: (edge: EdgeInterface) => void;
+  onEdgeUpdated?: (edge: EdgeInterface) => void;
+};
+
+type InterfaceGraphEngineProps = {
   graph: Graph;
   layout: GraphLayout;
+  onLayoutStart?: (detail?: GraphLayoutEventDetail) => void;
+  onLayoutChange?: (detail?: GraphLayoutEventDetail) => void;
+  onLayoutDone?: (detail?: GraphLayoutEventDetail) => void;
+  onLayoutError?: (error?: unknown) => void;
+  onTransactionStart?: () => void;
+  onTransactionEnd?: () => void;
+  onNodeAdded?: (node: NodeInterface) => void;
+  onNodeRemoved?: (node: NodeInterface) => void;
+  onNodeUpdated?: (node: NodeInterface) => void;
+  onEdgeAdded?: (edge: EdgeInterface) => void;
+  onEdgeRemoved?: (edge: EdgeInterface) => void;
+  onEdgeUpdated?: (edge: EdgeInterface) => void;
 };
 
-/** Graph engine controls the graph data and layout calculation */
-export class GraphEngine extends EventTarget {
-  props: Readonly<Required<GraphEngineProps>>;
+export type GraphEngineProps = ClassicGraphEngineProps | InterfaceGraphEngineProps;
 
+/** Graph engine controls the graph data and layout calculation */
+export class GraphEngine {
+  private _props: GraphEngineProps;
   private readonly _graph: Graph;
   private readonly _layout: GraphLayout;
-  private readonly _cache = new Cache<'nodes' | 'edges', Node[] | Edge[]>();
+  private readonly _cache = new Cache<'nodes' | 'edges', NodeInterface[] | EdgeInterface[]>();
   private _layoutDirty = false;
   private _transactionInProgress = false;
+  private _graphCallbacksAttached = false;
+  private _layoutCallbacksAttached = false;
 
   constructor(props: GraphEngineProps);
   /** @deprecated Use props constructor: new GraphEngine(props) */
-  constructor(graph: Graph, layout: GraphLayout);
-
-  constructor(props: GraphEngineProps | Graph, layout?: GraphLayout) {
-    super();
-    if (props instanceof Graph) {
-      props = {
-        graph: props,
-        layout
-      };
+  constructor(graph: ClassicGraph, layout: GraphLayout);
+
+  constructor(props: GraphEngineProps | ClassicGraph, layout?: GraphLayout) {
+    let normalizedProps: GraphEngineProps;
+    if (props instanceof ClassicGraph) {
+      if (!(layout instanceof GraphLayout)) {
+        throw new Error('GraphEngine: legacy graphs require a GraphLayout instance.');
+      }
+      normalizedProps = {graph: props, layout};
+    } else {
+      normalizedProps = props;
     }
 
-    this.props = props;
-    this._graph = props.graph;
-    this._layout = props.layout;
+    this._props = {...normalizedProps};
+
+    this._graph = normalizedProps.graph;
+    this._layout = normalizedProps.layout;
+  }
+
+  get props(): GraphEngineProps {
+    return {...this._props};
+  }
+
+  setProps(props: Partial<Omit<GraphEngineProps, 'graph' | 'layout'>>): void {
+    this._props = {
+      ...this._props,
+      ...props,
+      graph: this._props.graph,
+      layout: this._props.layout
+    } as GraphEngineProps;
   }
 
   /** Getters */
 
-  getNodes = (): Node[] => {
+  getNodes = (): NodeInterface[] => {
     this._updateCache('nodes', () =>
-      this._graph.getNodes().filter((node) => this.getNodePosition(node))
+      Array.from(this._graph.getNodes()).filter((node) => {
+        const position = this.getNodePosition(node);
+        return position !== null && position !== undefined;
+      })
     );
 
-    return this._cache.get('nodes') as Node[];
+    return (this._cache.get('nodes') as NodeInterface[]) ?? [];
   };
 
   getEdges = () => {
     this._updateCache('edges', () =>
-      this._graph.getEdges().filter((edge) => this.getEdgePosition(edge))
+      Array.from(this._graph.getEdges()).filter((edge) => {
+        const layout = this.getEdgePosition(edge);
+        return layout !== null && layout !== undefined;
+      })
     );
 
-    return this._cache.get('edges') as Edge[];
+    return (this._cache.get('edges') as EdgeInterface[]) ?? [];
   };
 
-  getNodePosition = (node: Node) => this._layout.getNodePosition(node);
+  getNodePosition = (node: NodeInterface) => {
+    return this._layout.getNodePosition(node) ?? null;
+  };
 
-  getEdgePosition = (edge: Edge) => this._layout.getEdgePosition(edge);
+  getEdgePosition = (edge: EdgeInterface) => {
+    return this._layout.getEdgePosition(edge) ?? null;
+  };
 
   getGraphVersion = () => this._graph.version;
 
@@ -72,77 +130,74 @@ export class GraphEngine extends EventTarget {
 
   getLayoutState = () => this._layout.state;
 
-  getLayoutBounds = (): Bounds2D | null => this._layout.getBounds();
+  getLayoutBounds = (): Bounds2D | null => this._layout.getBounds() ?? null;
 
   /** Operations on the graph */
 
-  lockNodePosition = (node, x, y) => this._layout.lockNodePosition(node, x, y);
+  lockNodePosition = (node: NodeInterface, x: number, y: number) => {
+    this._layout.lockNodePosition(node, x, y);
+  };
+
+  unlockNodePosition = (node: NodeInterface) => {
+    this._layout.unlockNodePosition(node);
+  };
+
+  findNode(nodeId: string | number): NodeInterface | undefined {
+    return this._graph.findNode?.(nodeId) ?? this._graph.findNodeById?.(nodeId);
+  }
 
-  unlockNodePosition = (node) => this._layout.unlockNodePosition(node);
+  createStylesheetEngine(
+    style: GraphStylesheet,
+    options: {stateUpdateTrigger?: unknown} = {}
+  ): GraphStylesheetEngine {
+    return new GraphStylesheetEngine(style, options);
+  }
 
   /**
    * @fires GraphEngine#onLayoutStart
    */
-  _onLayoutStart = (event: Event) => {
+  _onLayoutStart = (detail?: GraphLayoutEventDetail) => {
     log.log(0, 'GraphEngine: layout start')();
-    const detail = event instanceof CustomEvent ? (event.detail as GraphLayoutEventDetail) : undefined;
-    /**
-     * @event GraphEngine#onLayoutStart
-     * @type {CustomEvent}
-     */
-    this.dispatchEvent(new CustomEvent('onLayoutStart', {detail}));
+    this._props.onLayoutStart?.(detail);
   };
 
   /**
    * @fires GraphEngine#onLayoutChange
    */
-  _onLayoutChange = (event: Event) => {
+  _onLayoutChange = (detail?: GraphLayoutEventDetail) => {
     log.log(0, 'GraphEngine: layout update event')();
-    const detail = event instanceof CustomEvent ? (event.detail as GraphLayoutEventDetail) : undefined;
-    /**
-     * @event GraphEngine#onLayoutChange
-     * @type {CustomEvent}
-     */
-    this.dispatchEvent(new CustomEvent('onLayoutChange', {detail}));
+    this._props.onLayoutChange?.(detail);
   };
 
   /**
    * @fires GraphEngine#onLayoutDone
    */
-  _onLayoutDone = (event: Event) => {
+  _onLayoutDone = (detail?: GraphLayoutEventDetail) => {
     log.log(0, 'GraphEngine: layout end')();
-    const detail = event instanceof CustomEvent ? (event.detail as GraphLayoutEventDetail) : undefined;
-    /**
-     * @event GraphEngine#onLayoutDone
-     * @type {CustomEvent}
-     */
-    this.dispatchEvent(new CustomEvent('onLayoutDone', {detail}));
+    this._props.onLayoutDone?.(detail);
   };
 
   /**
    * @fires GraphEngine#onLayoutError
    */
-  _onLayoutError = (event: Event) => {
-    const detail = event instanceof CustomEvent ? event.detail : undefined;
-    /**
-     * @event GraphEngine#onLayoutError
-     * @type {CustomEvent}
-     */
-    this.dispatchEvent(new CustomEvent('onLayoutError', {detail}));
+  _onLayoutError = (error?: unknown) => {
+    this._props.onLayoutError?.(error);
   };
 
-  _onGraphStructureChanged = (entity) => {
+  _onGraphStructureChanged = () => {
     this._layoutDirty = true;
     this._graphChanged();
   };
 
   _onTransactionStart = () => {
     this._transactionInProgress = true;
+    this._props.onTransactionStart?.();
   };
 
   _onTransactionEnd = () => {
     this._transactionInProgress = false;
     this._graphChanged();
+    this._props.onTransactionEnd?.();
   };
 
   /** Layout calculations */
@@ -151,17 +206,8 @@ export class GraphEngine extends EventTarget {
     log.log(1, 'GraphEngine: run');
     // TODO: throw if running on a cleared engine
 
-    this._graph.addEventListener('transactionStart', this._onTransactionStart);
-    this._graph.addEventListener('transactionEnd', this._onTransactionEnd);
-    this._graph.addEventListener('onNodeAdded', this._onGraphStructureChanged);
-    this._graph.addEventListener('onNodeRemoved', this._onGraphStructureChanged);
-    this._graph.addEventListener('onEdgeAdded', this._onGraphStructureChanged);
-    this._graph.addEventListener('onEdgeRemoved', this._onGraphStructureChanged);
-
-    this._layout.addEventListener('onLayoutStart', this._onLayoutStart);
-    this._layout.addEventListener('onLayoutChange', this._onLayoutChange);
-    this._layout.addEventListener('onLayoutDone', this._onLayoutDone);
-    this._layout.addEventListener('onLayoutError', this._onLayoutError);
+    this._attachGraphCallbacks();
+    this._attachLayoutCallbacks();
 
     this._layout.initializeGraph(this._graph);
     this._layout.start();
@@ -169,22 +215,17 @@ export class GraphEngine extends EventTarget {
 
   clear = () => {
     log.log(1, 'GraphEngine: end');
-    this._graph.removeEventListener('transactionStart', this._onTransactionStart);
-    this._graph.removeEventListener('transactionEnd', this._onTransactionEnd);
-    this._graph.removeEventListener('onNodeAdded', this._onGraphStructureChanged);
-    this._graph.removeEventListener('onNodeRemoved', this._onGraphStructureChanged);
-    this._graph.removeEventListener('onEdgeAdded', this._onGraphStructureChanged);
-    this._graph.removeEventListener('onEdgeRemoved', this._onGraphStructureChanged);
-
-    this._layout.removeEventListener('onLayoutStart', this._onLayoutStart);
-    this._layout.removeEventListener('onLayoutChange', this._onLayoutChange);
-    this._layout.removeEventListener('onLayoutDone', this._onLayoutDone);
-    this._layout.removeEventListener('onLayoutError', this._onLayoutError);
+    this._detachGraphCallbacks();
+    this._detachLayoutCallbacks();
   };
 
-  resume = () => this._layout.resume();
+  resume = () => {
+    this._layout.resume();
+  };
 
-  stop = () => this._layout.stop();
+  stop = () => {
+    this._layout.stop();
+  };
 
   _graphChanged = () => {
     if (this._layoutDirty && !this._transactionInProgress) {
@@ -200,6 +241,82 @@ export class GraphEngine extends EventTarget {
   };
 
   _updateCache(key, updateValue) {
-    this._cache.set(key, updateValue, this._graph.version + this._layout.version);
+    this._cache.set(key, updateValue, this.getGraphVersion() + this.getLayoutLastUpdate());
+  }
+
+  private _attachGraphCallbacks() {
+    if (this._graphCallbacksAttached) {
+      return;
+    }
+    this._graph.updateProps({
+      onTransactionStart: this._onTransactionStart,
+      onTransactionEnd: this._onTransactionEnd,
+      onNodeAdded: (node) => {
+        this._onGraphStructureChanged();
+        this._props.onNodeAdded?.(node);
+      },
+      onNodeRemoved: (node) => {
+        this._onGraphStructureChanged();
+        this._props.onNodeRemoved?.(node);
+      },
+      onNodeUpdated: (node) => {
+        this._props.onNodeUpdated?.(node);
+      },
+      onEdgeAdded: (edge) => {
+        this._onGraphStructureChanged();
+        this._props.onEdgeAdded?.(edge);
+      },
+      onEdgeRemoved: (edge) => {
+        this._onGraphStructureChanged();
+        this._props.onEdgeRemoved?.(edge);
+      },
+      onEdgeUpdated: (edge) => {
+        this._props.onEdgeUpdated?.(edge);
+      }
+    });
+    this._graphCallbacksAttached = true;
+  }
+
+  private _detachGraphCallbacks() {
+    if (!this._graphCallbacksAttached) {
+      return;
+    }
+    this._graph.updateProps({
+      onTransactionStart: undefined,
+      onTransactionEnd: undefined,
+      onNodeAdded: undefined,
+      onNodeRemoved: undefined,
+      onNodeUpdated: undefined,
+      onEdgeAdded: undefined,
+      onEdgeRemoved: undefined,
+      onEdgeUpdated: undefined
+    });
+    this._graphCallbacksAttached = false;
+  }
+
+  private _attachLayoutCallbacks() {
+    if (this._layoutCallbacksAttached) {
+      return;
+    }
+    this._layout.setProps({
+      onLayoutStart: this._onLayoutStart,
+      onLayoutChange: this._onLayoutChange,
+      onLayoutDone: this._onLayoutDone,
+      onLayoutError: this._onLayoutError
+    });
+    this._layoutCallbacksAttached = true;
+  }
+
+  private _detachLayoutCallbacks() {
+    if (!this._layoutCallbacksAttached) {
+      return;
+    }
+    this._layout.setProps({
+      onLayoutStart: undefined,
+      onLayoutChange: undefined,
+      onLayoutDone: undefined,
+      onLayoutError: undefined
+    });
+    this._layoutCallbacksAttached = false;
   }
 }

package/src/core/graph-layout.ts

@@ -4,9 +4,7 @@
 
 import type {Bounds2D} from '@math.gl/types';
 
-import type {Graph} from '../graph/graph';
-import type {Node} from '../graph/node';
-import type {Edge} from '../graph/edge';
+import type {Graph, NodeInterface, EdgeInterface} from '../graph/graph';
 
 import isEqual from 'lodash.isequal';
 import {log} from '../utils/log';
@@ -18,16 +16,30 @@ export type GraphLayoutEventDetail = {
   bounds: Bounds2D | null;
 };
 
-export type GraphLayoutProps = {};
+export type GraphLayoutProps = {
+  onLayoutStart?: (detail?: GraphLayoutEventDetail) => void;
+  onLayoutChange?: (detail?: GraphLayoutEventDetail) => void;
+  onLayoutDone?: (detail?: GraphLayoutEventDetail) => void;
+  onLayoutError?: (error?: unknown) => void;
+};
+
 
-/** All the layout classes are extended from this base layout class. */
 export abstract class GraphLayout<
-  OptionsT extends GraphLayoutProps = GraphLayoutProps
-> extends EventTarget {
-  /** Name of the layout. */
-  protected readonly _name: string = 'GraphLayout';
-  /** Extra configuration options of the layout. */
-  protected _options: OptionsT;
+  PropsT extends GraphLayoutProps = GraphLayoutProps
+> {
+  static defaultProps: Readonly<Required<GraphLayoutProps>> = {
+    onLayoutStart: undefined,
+    onLayoutChange: undefined,
+    onLayoutDone: undefined,
+    onLayoutError: undefined
+  };
+
+  get [Symbol.toStringTag](): string {
+    return 'GraphLayout';
+  }
+
+  /** Extra configuration props of the layout. */
+  protected props: Required<PropsT>;
 
   /**
    * Last computed layout bounds in local layout coordinates.
@@ -42,11 +54,22 @@ export abstract class GraphLayout<
 
   /**
    * Constructor of GraphLayout
-   * @param options extra configuration options of the layout
+   * @param props extra configuration props of the layout
    */
-  constructor(options: OptionsT) {
-    super();
-    this._options = options;
+  constructor(props: PropsT, defaultProps?: Required<PropsT>) {
+    this.props = {
+      ...GraphLayout.defaultProps,
+      ...defaultProps,
+      ...props
+    };
+  }
+
+  getProps(): PropsT {
+    return {...this.props};
+  }
+
+  setProps(props: Partial<PropsT>): void {
+    this.props = {...this.props, ...props};
   }
 
   /**
@@ -58,18 +81,18 @@ export abstract class GraphLayout<
     if (!layout || !(layout instanceof GraphLayout)) {
       return false;
     }
-    return this._name === layout._name && isEqual(this._options, layout._options);
+    return this instanceof layout.constructor && isEqual(this.props, layout.props);
   }
 
   // Accessors
 
   /** access the position of the node in the layout */
-  getNodePosition(node: Node): [number, number] {
+  getNodePosition(node: NodeInterface): [number, number] {
     return [0, 0];
   }
 
   /** access the layout information of the edge */
-  getEdgePosition(edge: Edge) {
+  getEdgePosition(edge: EdgeInterface) {
     return {
       type: 'line',
       sourcePosition: [0, 0],
@@ -84,13 +107,13 @@ export abstract class GraphLayout<
    * @param  x    x coordinate
    * @param  y    y coordinate
    */
-  lockNodePosition(node: Node, x: number, y: number) {}
+  lockNodePosition(node: NodeInterface, x: number, y: number) {}
 
   /**
    * Unlock the node, the node will be able to move freely.
    * @param  {Object} node Node to be unlocked
    */
-  unlockNodePosition(node: Node) {}
+  unlockNodePosition(node: NodeInterface) {}
 
   /** Returns the last computed layout bounds, if available. */
   getBounds(): Bounds2D | null {
@@ -100,9 +123,9 @@ export abstract class GraphLayout<
     /** virtual functions: will be implemented in the child class */
 
   /** first time to pass the graph data into this layout */
-  abstract initializeGraph(graph: Graph);
+  abstract initializeGraph(graph: Graph): void;
   /** update the existing graph */
-  abstract updateGraph(graph: Graph);
+  abstract updateGraph(graph: Graph): void;
   /** start the layout calculation */
   abstract start();
   /** update the layout calculation */
@@ -194,7 +217,7 @@ export abstract class GraphLayout<
 
   /** @fires GraphLayout#onLayoutStart */
   protected _onLayoutStart = (): void => {
-    log.log(0, `GraphLayout(${this._name}): start`)();
+    log.log(0, `GraphLayout(${this}): start`)();
     this._updateBounds();
     this._updateState('calculating');
 
@@ -204,12 +227,12 @@ export abstract class GraphLayout<
      * @type {CustomEvent}
      */
     const detail: GraphLayoutEventDetail = {bounds: this._bounds};
-    this.dispatchEvent(new CustomEvent<GraphLayoutEventDetail>('onLayoutStart', {detail}));
+    this.props.onLayoutStart?.(detail);
   };
 
   /** @fires GraphLayout#onLayoutChange */
   protected _onLayoutChange = (): void => {
-    log.log(0, `GraphLayout(${this._name}): update`)();
+    log.log(0, `GraphLayout(${this}): update`)();
     this._updateBounds();
     this._updateState('calculating');
 
@@ -219,12 +242,12 @@ export abstract class GraphLayout<
      * @type {CustomEvent}
      */
     const detail: GraphLayoutEventDetail = {bounds: this._bounds};
-    this.dispatchEvent(new CustomEvent<GraphLayoutEventDetail>('onLayoutChange', {detail}));
+    this.props.onLayoutChange?.(detail);
   };
 
   /** @fires GraphLayout#onLayoutDone */
   protected _onLayoutDone = (): void => {
-    log.log(0, `GraphLayout(${this._name}): end`)();
+    log.log(0, `GraphLayout(${this}): end`)();
     this._updateBounds();
     this._updateState('done');
 
@@ -234,7 +257,7 @@ export abstract class GraphLayout<
      * @type {CustomEvent}
      */
     const detail: GraphLayoutEventDetail = {bounds: this._bounds};
-    this.dispatchEvent(new CustomEvent<GraphLayoutEventDetail>('onLayoutDone', {detail}));
+    this.props.onLayoutDone?.(detail);
   };
 
   /** @fires GraphLayout#onLayoutError */
@@ -246,6 +269,6 @@ export abstract class GraphLayout<
      * @event GraphLayout#onLayoutError
      * @type {CustomEvent}
      */
-    this.dispatchEvent(new CustomEvent('onLayoutError'));
+    this.props.onLayoutError?.();
   };
 }