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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@deck.gl-community/graph-layers",
-  "version": "9.1.0-beta.8",
+  "version": "9.2.0-beta.2",
   "description": "WebGL2-Powered library for Graph Visualization",
   "keywords": [
     "graph",
@@ -19,6 +19,11 @@
       "types": "./dist/index.d.ts",
       "require": "./dist/index.cjs",
       "import": "./dist/index.js"
+    },
+    "./graph-style-schema.json": "./dist/graph-style-schema.json",
+    "./graph-style-schema.cdn": {
+      "types": "./dist/graph-style-schema.cdn.d.ts",
+      "default": "./dist/graph-style-schema.cdn.js"
     }
   },
   "files": [
@@ -26,21 +31,27 @@
     "src"
   ],
   "scripts": {
+    "build": "tsc -b tsconfig.json && node ./scripts/generate-graphstyle-schema.mjs",
+    "build:schema": "node ./scripts/generate-graphstyle-schema.mjs",
     "test": "vitest run",
     "test-watch": "vitest"
   },
   "license": "MIT",
   "dependencies": {
-    "@deck.gl/core": "^9.1.12",
-    "@deck.gl/layers": "^9.1.0",
-    "@deck.gl/widgets": "^9.1.0",
-    "@luma.gl/core": "^9.1.9",
+    "@deck.gl/core": "~9.2.1",
+    "@deck.gl/layers": "~9.2.1",
+    "@deck.gl/widgets": "~9.2.1",
+    "@loaders.gl/core": "^4.2.0",
+    "@luma.gl/core": "~9.2.0",
+    "@luma.gl/engine": "~9.2.0",
+    "@luma.gl/shadertools": "~9.2.0",
     "@probe.gl/log": "^4.0.4",
     "cardinal-spline-js": "^2.3.10",
     "color": "^4.2.3",
     "core-js": "^3.29.0",
     "d3": "^7.8.2",
     "d3-array": "^3.2.2",
+    "d3-dag": "^1.1.0",
     "d3-force": "^3.0.0",
     "d3-format": "^3.1.0",
     "d3-scale": "^4.0.2",
@@ -51,7 +62,12 @@
     "raf": "^3.4.1"
   },
   "devDependencies": {
-    "ngraph.generators": "^20.1.0"
+    "ngraph.generators": "^20.1.0",
+    "zod": "^4.0.0",
+    "zod-to-json-schema": "^3.22.5"
   },
-  "gitHead": "63ffab49b65290486fcc7c8e3891c090f4ef5136"
+  "peerDependencies": {
+    "zod": "^3.23.8 || ^4.0.0"
+  },
+  "gitHead": "b434bcba10800f27e95a7c9e6c4c7edd0b915773"
 }

package/src/_deprecated/old-constants.ts

@@ -0,0 +1,122 @@
+// deck.gl-community
+// SPDX-License-Identifier: MIT
+// Copyright (c) vis.gl contributors
+
+import {EdgeDecoratorType, EdgeState, EdgeType, LayoutState, NodeState, NodeType} from '../core/constants';
+import {Marker} from '../layers/common-layers/marker-layer/marker-list';
+
+/** Markers supported by graph-layers @deprecated v9.2: Use string literals */
+export const MARKER_TYPE = {
+  'bell-filled': 'bell-filled',
+  bell: 'bell',
+  'bookmark-filled': 'bookmark-filled',
+  bookmark: 'bookmark',
+  'cd-filled': 'cd-filled',
+  cd: 'cd',
+  checkmark: 'checkmark',
+  'circle-check-filled': 'circle-check-filled',
+  'circle-check': 'circle-check',
+  'circle-filled': 'circle-filled',
+  'circle-i-filled': 'circle-i-filled',
+  'circle-i': 'circle-i',
+  'circle-minus-filled': 'circle-minus-filled',
+  'circle-minus': 'circle-minus',
+  'circle-plus-filled': 'circle-plus-filled',
+  'circle-plus': 'circle-plus',
+  'circle-questionmark-filled': 'circle-questionmark-filled',
+  'circle-questionmark': 'circle-questionmark',
+  'circle-slash-filled': 'circle-slash-filled',
+  'circle-slash': 'circle-slash',
+  'circle-x-filled': 'circle-x-filled',
+  'circle-x': 'circle-x',
+  circle: 'circle',
+  'diamond-filled': 'diamond-filled',
+  diamond: 'diamond',
+  'flag-filled': 'flag-filled',
+  flag: 'flag',
+  gear: 'gear',
+  'heart-filled': 'heart-filled',
+  heart: 'heart',
+  'location-marker-filled': 'location-marker-filled',
+  'location-marker': 'location-marker',
+  'octagonal-star-filled': 'octagonal-star-filled',
+  'octagonal-star': 'octagonal-star',
+  'person-filled': 'person-filled',
+  person: 'person',
+  'pin-filled': 'pin-filled',
+  pin: 'pin',
+  'plus-small': 'plus-small',
+  plus: 'plus',
+  'rectangle-filled': 'rectangle-filled',
+  rectangle: 'rectangle',
+  'star-filled': 'star-filled',
+  star: 'star',
+  'tag-filled': 'tag-filled',
+  tag: 'tag',
+  'thumb-down-filled': 'thumb-down-filled',
+  'thumb-down': 'thumb-down',
+  'thumb-up': 'thumb-up',
+  'thumb_up-filled': 'thumb_up-filled',
+  'triangle-down-filled': 'triangle-down-filled',
+  'triangle-down': 'triangle-down',
+  'triangle-left-filled': 'triangle-left-filled',
+  'triangle-left': 'triangle-left',
+  'triangle-right-filled': 'triangle-right-filled',
+  'triangle-right': 'triangle-right',
+  'triangle-up-filled': 'triangle-up-filled',
+  'triangle-up': 'triangle-up',
+  'x-small': 'x-small',
+  x: 'x'
+} as const satisfies Record<Marker, Marker>;
+/* eslint-enable */
+
+
+/** The interaction state of a node. @deprecated v9.2: Use string literals */
+export const NODE_STATE = {
+  DEFAULT: 'default',
+  HOVER: 'hover',
+  DRAGGING: 'dragging',
+  SELECTED: 'selected'
+} as const satisfies Record<string, NodeState>;
+
+/** The interaction state of an edge. @deprecated v9.2: Use string literals */
+export const EDGE_STATE = {
+  DEFAULT: 'default',
+  HOVER: 'hover',
+  DRAGGING: 'dragging',
+  SELECTED: 'selected'
+} as const satisfies Record<string, EdgeState>;
+
+/** The visual type of a node. @deprecated v9.2: Use string literals */
+export const NODE_TYPE = {
+  CIRCLE: 'circle',
+  RECTANGLE: 'rectangle',
+  ROUNDED_RECTANGLE: 'rounded-rectangle',
+  PATH_ROUNDED_RECTANGLE: 'path-rounded-rectangle',
+  ICON: 'icon',
+  LABEL: 'label',
+  MARKER: 'marker'
+} as const satisfies Record<string, NodeType> ;
+
+/** The visual type of an edge. @deprecated v9.2: Use string literals */
+export const EDGE_TYPE = {
+  SPLINE_CURVE: 'spline',
+  LINE: 'line',
+  PATH: 'path'
+} as const satisfies Record<string, EdgeType> ;
+
+/** Decorators on an edge. @deprecated v9.2: Use string literals */
+export const EDGE_DECORATOR_TYPE = {
+  LABEL: 'label',
+  FLOW: 'flow',
+  ARROW: 'arrow'
+} as const satisfies Record<string, EdgeDecoratorType> ;
+
+/** the status of the layout. @deprecated v9.2: Use string literals */
+export const LAYOUT_STATE = {
+  INIT: 'init',
+  START: 'start',
+  CALCULATING: 'calculating',
+  DONE: 'done',
+  ERROR: 'error'
+} as const satisfies Record<string, LayoutState> ;

package/src/core/constants.ts

@@ -2,57 +2,35 @@
 // SPDX-License-Identifier: MIT
 // Copyright (c) vis.gl contributors
 
-import {MarkerList} from '../layers/common-layers/marker-layer/marker-list';
+export {Marker} from '../layers/common-layers/marker-layer/marker-list';
 
-/** All the markers supported by node type MARKER */
-export const MARKER_TYPE = MarkerList;
+/** The interaction state of a node. */
+export type NodeState = 'default' | 'hover' | 'dragging' | 'selected';
 
-export type ValueOf<T> = T[keyof T];
-
-// the interaction state of a node.
-export const NODE_STATE = {
-  DEFAULT: 'default',
-  HOVER: 'hover',
-  DRAGGING: 'dragging',
-  SELECTED: 'selected'
-};
-
-export const EDGE_STATE = {
-  DEFAULT: 'default',
-  HOVER: 'hover',
-  DRAGGING: 'dragging',
-  SELECTED: 'selected'
-};
+/** The interaction state of an edge. */
+export type EdgeState = 'default' | 'hover' | 'dragging' | 'selected';
 
 // node visual marker type
-export const NODE_TYPE = {
-  CIRCLE: 'CIRCLE',
-  RECTANGLE: 'RECTANGLE',
-  ROUNDED_RECTANGLE: 'ROUNDED_RECTANGLE',
-  PATH_ROUNDED_RECTANGLE: 'PATH_ROUNDED_RECTANGLE',
-  ICON: 'ICON',
-  LABEL: 'LABEL',
-  MARKER: 'MARKER'
-};
+export type NodeType =
+  | 'circle'
+  | 'rectangle'
+  | 'rounded-rectangle'
+  | 'path-rounded-rectangle'
+  | 'icon'
+  | 'label'
+  | 'marker';
 
 // edge shape
+export type EdgeType = 'spline' | 'line' | 'path';
+
 export const EDGE_TYPE = {
-  SPLINE_CURVE: 'SPLINE_CURVE',
-  LINE: 'LINE',
-  PATH: 'PATH'
-};
+  SPLINE: 'spline',
+  LINE: 'line',
+  PATH: 'path'
+} as const satisfies Record<string, EdgeType>;
 
 // decorators on edges
-export const EDGE_DECORATOR_TYPE = {
-  LABEL: 'EDGE_LABEL',
-  FLOW: 'FLOW'
-};
+export type EdgeDecoratorType = 'label' | 'flow' | 'arrow';
 
 // the status of the layout
-export const LAYOUT_STATE = {
-  INIT: 'INIT',
-  START: 'START',
-  CALCULATING: 'CALCULATING',
-  DONE: 'DONE',
-  ERROR: 'ERROR'
-};
+export type LayoutState = 'init' | 'start' | 'calculating' | 'done' | 'error';

package/src/core/graph-engine.ts

@@ -2,11 +2,14 @@
 // SPDX-License-Identifier: MIT
 // Copyright (c) vis.gl contributors
 
+import type {Bounds2D} from '@math.gl/types';
+
 import type {Node} from '../graph/node';
 import {Edge} from '../graph/edge';
 import {Graph} from '../graph/graph';
-import {GraphLayout} from './graph-layout';
+import {GraphLayout, type GraphLayoutEventDetail} from './graph-layout';
 import {Cache} from './cache';
+import {log} from '../utils/log';
 
 export type GraphEngineProps = {
   graph: Graph;
@@ -69,6 +72,8 @@ export class GraphEngine extends EventTarget {
 
   getLayoutState = () => this._layout.state;
 
+  getLayoutBounds = (): Bounds2D | null => this._layout.getBounds();
+
   /** Operations on the graph */
 
   lockNodePosition = (node, x, y) => this._layout.lockNodePosition(node, x, y);
@@ -78,45 +83,52 @@ export class GraphEngine extends EventTarget {
   /**
    * @fires GraphEngine#onLayoutStart
    */
-  _onLayoutStart = () => {
+  _onLayoutStart = (event: Event) => {
+    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'));
+    this.dispatchEvent(new CustomEvent('onLayoutStart', {detail}));
   };
 
   /**
    * @fires GraphEngine#onLayoutChange
    */
-  _onLayoutChange = () => {
+  _onLayoutChange = (event: Event) => {
+    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'));
+    this.dispatchEvent(new CustomEvent('onLayoutChange', {detail}));
   };
 
   /**
    * @fires GraphEngine#onLayoutDone
    */
-  _onLayoutDone = () => {
+  _onLayoutDone = (event: Event) => {
+    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'));
+    this.dispatchEvent(new CustomEvent('onLayoutDone', {detail}));
   };
 
   /**
    * @fires GraphEngine#onLayoutError
    */
-  _onLayoutError = () => {
+  _onLayoutError = (event: Event) => {
+    const detail = event instanceof CustomEvent ? event.detail : undefined;
     /**
      * @event GraphEngine#onLayoutError
      * @type {CustomEvent}
      */
-    this.dispatchEvent(new CustomEvent('onLayoutError'));
+    this.dispatchEvent(new CustomEvent('onLayoutError', {detail}));
   };
 
   _onGraphStructureChanged = (entity) => {
@@ -136,6 +148,7 @@ export class GraphEngine extends EventTarget {
   /** Layout calculations */
 
   run = () => {
+    log.log(1, 'GraphEngine: run');
     // TODO: throw if running on a cleared engine
 
     this._graph.addEventListener('transactionStart', this._onTransactionStart);
@@ -155,6 +168,7 @@ 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);
@@ -179,6 +193,7 @@ export class GraphEngine extends EventTarget {
   };
 
   _updateLayout = () => {
+    log.log(0, 'GraphEngine: layout update');
     this._layout.updateGraph(this._graph);
     this._layout.update();
     this._layoutDirty = false;

package/src/core/graph-layout.ts

@@ -2,29 +2,43 @@
 // SPDX-License-Identifier: MIT
 // Copyright (c) vis.gl contributors
 
+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 isEqual from 'lodash.isequal';
-import {EDGE_TYPE} from './constants';
+import {log} from '../utils/log';
 
 // the status of the layout
-export type GraphLayoutState = 'INIT' | 'START' | 'CALCULATING' | 'DONE' | 'ERROR';
+export type GraphLayoutState = 'init' | 'start' | 'calculating' | 'done' | 'error';
+
+export type GraphLayoutEventDetail = {
+  bounds: Bounds2D | null;
+};
 
-export type GraphLayoutOptions = {};
+export type GraphLayoutProps = {};
 
 /** All the layout classes are extended from this base layout class. */
-export class GraphLayout<
-  OptionsT extends GraphLayoutOptions = GraphLayoutOptions
+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;
 
+  /**
+   * Last computed layout bounds in local layout coordinates.
+   *
+   * Subclasses should update this value by overriding {@link _updateBounds}
+   * so it reflects the latest geometry before layout lifecycle events fire.
+   */
+  protected _bounds: Bounds2D | null = null;
+
   public version = 0;
-  public state: GraphLayoutState = 'INIT';
+  public state: GraphLayoutState = 'init';
 
   /**
    * Constructor of GraphLayout
@@ -47,28 +61,17 @@ export class GraphLayout<
     return this._name === layout._name && isEqual(this._options, layout._options);
   }
 
-  /** virtual functions: will be implemented in the child class */
+  // Accessors
 
-  /** first time to pass the graph data into this layout */
-  initializeGraph(graph: Graph) {}
-  /** update the existing graph */
-  updateGraph(graph: Graph) {}
-  /** start the layout calculation */
-  start() {}
-  /** update the layout calculation */
-  update() {}
-  /** resume the layout calculation */
-  resume() {}
-  /** stop the layout calculation */
-  stop() {}
   /** access the position of the node in the layout */
   getNodePosition(node: Node): [number, number] {
     return [0, 0];
   }
+
   /** access the layout information of the edge */
   getEdgePosition(edge: Edge) {
     return {
-      type: EDGE_TYPE.LINE,
+      type: 'line',
       sourcePosition: [0, 0],
       targetPosition: [0, 0],
       controlPoints: []
@@ -89,52 +92,154 @@ export class GraphLayout<
    */
   unlockNodePosition(node: Node) {}
 
+  /** Returns the last computed layout bounds, if available. */
+  getBounds(): Bounds2D | null {
+    return this._bounds;
+  }
+
+    /** virtual functions: will be implemented in the child class */
+
+  /** first time to pass the graph data into this layout */
+  abstract initializeGraph(graph: Graph);
+  /** update the existing graph */
+  abstract updateGraph(graph: Graph);
+  /** start the layout calculation */
+  abstract start();
+  /** update the layout calculation */
+  abstract update();
+  /** resume the layout calculation */
+  abstract resume();
+  /** stop the layout calculation */
+  abstract stop();
+
+
   // INTERNAL METHODS
 
-  protected _updateState(state) {
+  /** Hook for subclasses to update bounds prior to emitting events. */
+  // eslint-disable-next-line @typescript-eslint/no-empty-function
+  protected _updateBounds(): void {}
+
+  /**
+   * Utility for subclasses to derive layout bounds from an iterable of [x, y] positions.
+   * @param positions Iterable of node positions.
+   * @returns Layout bounds for the supplied positions or `null` if none are finite.
+   */
+  protected _calculateBounds(
+    positions: Iterable<Readonly<[number, number]> | null | undefined>
+  ): Bounds2D | null {
+    let minX = Number.POSITIVE_INFINITY;
+    let maxX = Number.NEGATIVE_INFINITY;
+    let minY = Number.POSITIVE_INFINITY;
+    let maxY = Number.NEGATIVE_INFINITY;
+
+    for (const position of positions) {
+      if (!position) {
+        // eslint-disable-next-line no-continue
+        continue;
+      }
+      const [x, y] = position;
+      if (!Number.isFinite(x) || !Number.isFinite(y)) {
+        // eslint-disable-next-line no-continue
+        continue;
+      }
+
+      minX = Math.min(minX, x);
+      maxX = Math.max(maxX, x);
+      minY = Math.min(minY, y);
+      maxY = Math.max(maxY, y);
+    }
+
+    if (minX === Number.POSITIVE_INFINITY) {
+      return null;
+    }
+
+    return [
+      [minX, minY],
+      [maxX, maxY]
+    ];
+  }
+
+  /**
+   * Attempt to coerce an arbitrary value into a finite 2D point.
+   * @param value Candidate value that may represent a position.
+   * @returns Finite [x, y] tuple or null if the value cannot be interpreted.
+   */
+  protected _normalizePosition(value: unknown): [number, number] | null {
+    if (Array.isArray(value) && value.length >= 2) {
+      const [x, y] = value as [unknown, unknown];
+      if (this._isFiniteNumber(x) && this._isFiniteNumber(y)) {
+        return [x, y];
+      }
+      return null;
+    }
+
+    if (value && typeof value === 'object') {
+      const {x, y} = value as {x?: unknown; y?: unknown};
+      if (this._isFiniteNumber(x) && this._isFiniteNumber(y)) {
+        return [x, y];
+      }
+    }
+
+    return null;
+  }
+
+  private _isFiniteNumber(value: unknown): value is number {
+    return typeof value === 'number' && Number.isFinite(value);
+  }
+
+  protected _updateState(state: GraphLayoutState) {
     this.state = state;
     this.version += 1;
   }
 
   /** @fires GraphLayout#onLayoutStart */
   protected _onLayoutStart = (): void => {
-    this._updateState('CALCULATING');
+    log.log(0, `GraphLayout(${this._name}): start`)();
+    this._updateBounds();
+    this._updateState('calculating');
 
     /**
      * Layout calculation start.
      * @event GraphLayout#onLayoutChange
      * @type {CustomEvent}
      */
-    this.dispatchEvent(new CustomEvent('onLayoutStart'));
+    const detail: GraphLayoutEventDetail = {bounds: this._bounds};
+    this.dispatchEvent(new CustomEvent<GraphLayoutEventDetail>('onLayoutStart', {detail}));
   };
 
   /** @fires GraphLayout#onLayoutChange */
   protected _onLayoutChange = (): void => {
-    this._updateState('CALCULATING');
+    log.log(0, `GraphLayout(${this._name}): update`)();
+    this._updateBounds();
+    this._updateState('calculating');
 
     /**
      * Layout calculation iteration.
      * @event GraphLayout#onLayoutChange
      * @type {CustomEvent}
      */
-    this.dispatchEvent(new CustomEvent('onLayoutChange'));
+    const detail: GraphLayoutEventDetail = {bounds: this._bounds};
+    this.dispatchEvent(new CustomEvent<GraphLayoutEventDetail>('onLayoutChange', {detail}));
   };
 
   /** @fires GraphLayout#onLayoutDone */
   protected _onLayoutDone = (): void => {
-    this._updateState('DONE');
+    log.log(0, `GraphLayout(${this._name}): end`)();
+    this._updateBounds();
+    this._updateState('done');
 
     /**
      * Layout calculation is done.
      * @event GraphLayout#onLayoutDone
      * @type {CustomEvent}
      */
-    this.dispatchEvent(new CustomEvent('onLayoutDone'));
+    const detail: GraphLayoutEventDetail = {bounds: this._bounds};
+    this.dispatchEvent(new CustomEvent<GraphLayoutEventDetail>('onLayoutDone', {detail}));
   };
 
   /** @fires GraphLayout#onLayoutError */
   protected _onLayoutError = (): void => {
-    this._updateState('ERROR');
+    this._updateState('error');
 
     /**
      * Layout calculation went wrong.