@deck.gl-community/graph-layers 9.0.0

package/LICENSE

@@ -0,0 +1,20 @@
+Copyright (c) 2015 - 2021 Uber Technologies, Inc.
+Copyright (c) 2022 - 2023 react-graph-layers contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

package/README.md

@@ -0,0 +1,7 @@
+# graph-layers
+
+TBD
+
+<p align="center">
+  <img src="https://i.imgur.com/BF9aOEu.png" height="400" />
+</p>

package/dist/core/base-layout.d.ts

@@ -0,0 +1,71 @@
+export interface BaseLayoutOptions {
+}
+/**
+ * All the layout classes are extended from this base layout class.
+ */
+export declare class BaseLayout extends EventTarget {
+    /** Name of the layout. */
+    protected readonly _name: string;
+    /** Extra configuration options of the layout. */
+    protected _options: BaseLayoutOptions;
+    version: number;
+    state: string;
+    /**
+     * Constructor of BaseLayout
+     * @param  {Object} options extra configuration options of the layout
+     */
+    constructor(options?: BaseLayoutOptions);
+    /**
+     * @fires BaseLayout#onLayoutStart
+     * @protected
+     */
+    _onLayoutStart(): void;
+    /**
+     * @fires BaseLayout#onLayoutChange
+     * @protected
+     */
+    _onLayoutChange(): void;
+    /**
+     * @fires BaseLayout#onLayoutDone
+     * @protected
+     */
+    _onLayoutDone(): void;
+    /**
+     * @fires BaseLayout#onLayoutError
+     * @protected
+     */
+    _onLayoutError(): void;
+    /**
+     * Check the equality of two layouts
+     * @param  {Object} layout The layout to be compared.
+     * @return {Bool}   True if the layout is the same as itself.
+     */
+    equals(layout: BaseLayout): boolean;
+    /** virtual functions: will be implemented in the child class */
+    initializeGraph(graph: any): void;
+    updateGraph(graph: any): void;
+    start(): void;
+    update(): void;
+    resume(): void;
+    stop(): void;
+    getNodePosition(node: Node): [number, number];
+    getEdgePosition(edge: any): {
+        type: string;
+        sourcePosition: number[];
+        targetPosition: number[];
+        controlPoints: any[];
+    };
+    /**
+     * Pin the node to a designated position, and the node won't move anymore
+     * @param  {Object} node Node to be locked
+     * @param  {Number} x    x coordinate
+     * @param  {Number} y    y coordinate
+     */
+    lockNodePosition(node: any, x: any, y: any): void;
+    /**
+     * Unlock the node, the node will be able to move freely.
+     * @param  {Object} node Node to be unlocked
+     */
+    unlockNodePosition(node: any): void;
+    _updateState(state: any): void;
+}

package/dist/core/base-layout.js

@@ -0,0 +1,133 @@
+// deck.gl-community
+// SPDX-License-Identifier: MIT
+// Copyright (c) vis.gl contributors
+import isEqual from 'lodash.isequal';
+import { EDGE_TYPE, LAYOUT_STATE } from './constants';
+/**
+ * All the layout classes are extended from this base layout class.
+ */
+export class BaseLayout extends EventTarget {
+    /** Name of the layout. */
+    _name = 'BaseLayout';
+    /** Extra configuration options of the layout. */
+    _options;
+    version = 0;
+    state = LAYOUT_STATE.INIT;
+    /**
+     * Constructor of BaseLayout
+     * @param  {Object} options extra configuration options of the layout
+     */
+    constructor(options = {}) {
+        super();
+        this._options = options;
+    }
+    /**
+     * @fires BaseLayout#onLayoutStart
+     * @protected
+     */
+    _onLayoutStart() {
+        this._updateState(LAYOUT_STATE.CALCULATING);
+        /**
+         * Layout calculation start.
+         *
+         * @event BaseLayout#onLayoutChange
+         * @type {CustomEvent}
+         */
+        this.dispatchEvent(new CustomEvent('onLayoutStart'));
+    }
+    /**
+     * @fires BaseLayout#onLayoutChange
+     * @protected
+     */
+    _onLayoutChange() {
+        this._updateState(LAYOUT_STATE.CALCULATING);
+        /**
+         * Layout calculation iteration.
+         *
+         * @event BaseLayout#onLayoutChange
+         * @type {CustomEvent}
+         */
+        this.dispatchEvent(new CustomEvent('onLayoutChange'));
+    }
+    /**
+     * @fires BaseLayout#onLayoutDone
+     * @protected
+     */
+    _onLayoutDone() {
+        this._updateState(LAYOUT_STATE.DONE);
+        /**
+         * Layout calculation is done.
+         *
+         * @event BaseLayout#onLayoutDone
+         * @type {CustomEvent}
+         */
+        this.dispatchEvent(new CustomEvent('onLayoutDone'));
+    }
+    /**
+     * @fires BaseLayout#onLayoutError
+     * @protected
+     */
+    _onLayoutError() {
+        this._updateState(LAYOUT_STATE.ERROR);
+        /**
+         * Layout calculation went wrong.
+         *
+         * @event BaseLayout#onLayoutError
+         * @type {CustomEvent}
+         */
+        this.dispatchEvent(new CustomEvent('onLayoutError'));
+    }
+    /**
+     * Check the equality of two layouts
+     * @param  {Object} layout The layout to be compared.
+     * @return {Bool}   True if the layout is the same as itself.
+     */
+    equals(layout) {
+        if (!layout || !(layout instanceof BaseLayout)) {
+            return false;
+        }
+        return this._name === layout._name && isEqual(this._options, layout._options);
+    }
+    /** virtual functions: will be implemented in the child class */
+    // first time to pass the graph data into this layout
+    initializeGraph(graph) { }
+    // update the existing graph
+    updateGraph(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) {
+        return [0, 0];
+    }
+    // access the layout information of the edge
+    getEdgePosition(edge) {
+        return {
+            type: EDGE_TYPE.LINE,
+            sourcePosition: [0, 0],
+            targetPosition: [0, 0],
+            controlPoints: []
+        };
+    }
+    /**
+     * Pin the node to a designated position, and the node won't move anymore
+     * @param  {Object} node Node to be locked
+     * @param  {Number} x    x coordinate
+     * @param  {Number} y    y coordinate
+     */
+    lockNodePosition(node, x, y) { }
+    /**
+     * Unlock the node, the node will be able to move freely.
+     * @param  {Object} node Node to be unlocked
+     */
+    unlockNodePosition(node) { }
+    _updateState(state) {
+        this.state = state;
+        this.version += 1;
+    }
+}

package/dist/core/cache.d.ts

@@ -0,0 +1,14 @@
+export declare class Cache<K, V> {
+    private readonly _keys;
+    /**
+     * @param key The key of the cache
+     * @returns {*} The value of the cache as set by the `set` method.
+     */
+    get(key: K): V | undefined;
+    /**
+     * @param key The key of the cache
+     * @param createValue A callback to create the value of the cache if it is needed.
+     * @param version The version of the cache. If the version is smaller than the current version, the cache will not be updated.
+     */
+    set(key: K, createValue: (...args: unknown[]) => V, version: number): void;
+}

package/dist/core/cache.js

@@ -0,0 +1,26 @@
+// deck.gl-community
+// SPDX-License-Identifier: MIT
+// Copyright (c) vis.gl contributors
+export class Cache {
+    _keys = new Map();
+    /**
+     * @param key The key of the cache
+     * @returns {*} The value of the cache as set by the `set` method.
+     */
+    get(key) {
+        return this._keys.get(key)?.value;
+    }
+    /**
+     * @param key The key of the cache
+     * @param createValue A callback to create the value of the cache if it is needed.
+     * @param version The version of the cache. If the version is smaller than the current version, the cache will not be updated.
+     */
+    set(key, createValue, version) {
+        const cached = this._keys.get(key);
+        const keyUpdated = cached === undefined || version > cached.version;
+        if (!keyUpdated) {
+            return;
+        }
+        this._keys.set(key, { version, value: createValue() });
+    }
+}

package/dist/core/constants.d.ts

@@ -0,0 +1,101 @@
+/** All the markers supported by node type MARKER */
+export declare const MARKER_TYPE: {
+    'bell-filled': string;
+    bell: string;
+    'bookmark-filled': string;
+    bookmark: string;
+    'cd-filled': string;
+    cd: string;
+    checkmark: string;
+    'circle-check-filled': string;
+    'circle-check': string;
+    'circle-filled': string;
+    'circle-i-filled': string;
+    'circle-i': string;
+    'circle-minus-filled': string;
+    'circle-minus': string;
+    'circle-plus-filled': string;
+    'circle-plus': string;
+    'circle-questionmark-filled': string;
+    'circle-questionmark': string;
+    'circle-slash-filled': string;
+    'circle-slash': string;
+    'circle-x-filled': string;
+    'circle-x': string;
+    circle: string;
+    'diamond-filled': string;
+    diamond: string;
+    'flag-filled': string;
+    flag: string;
+    gear: string;
+    'heart-filled': string;
+    heart: string;
+    'location-marker-filled': string;
+    'location-marker': string;
+    'octagonal-star-filled': string;
+    'octagonal-star': string;
+    'person-filled': string;
+    person: string;
+    'pin-filled': string;
+    pin: string;
+    'plus-small': string;
+    plus: string;
+    'rectangle-filled': string;
+    rectangle: string;
+    'star-filled': string;
+    star: string;
+    'tag-filled': string;
+    tag: string;
+    'thumb-down-filled': string;
+    'thumb-down': string;
+    'thumb-up': string;
+    'thumb_up-filled': string;
+    'triangle-down-filled': string;
+    'triangle-down': string;
+    'triangle-left-filled': string;
+    'triangle-left': string;
+    'triangle-right-filled': string;
+    'triangle-right': string;
+    'triangle-up-filled': string;
+    'triangle-up': string;
+    'x-small': string;
+    x: string;
+};
+export type ValueOf<T> = T[keyof T];
+export declare const NODE_STATE: {
+    DEFAULT: string;
+    HOVER: string;
+    DRAGGING: string;
+    SELECTED: string;
+};
+export declare const EDGE_STATE: {
+    DEFAULT: string;
+    HOVER: string;
+    DRAGGING: string;
+    SELECTED: string;
+};
+export declare const NODE_TYPE: {
+    CIRCLE: string;
+    RECTANGLE: string;
+    ROUNDED_RECTANGLE: string;
+    PATH_ROUNDED_RECTANGLE: string;
+    ICON: string;
+    LABEL: string;
+    MARKER: string;
+};
+export declare const EDGE_TYPE: {
+    SPLINE_CURVE: string;
+    LINE: string;
+    PATH: string;
+};
+export declare const EDGE_DECORATOR_TYPE: {
+    LABEL: string;
+    FLOW: string;
+};
+export declare const LAYOUT_STATE: {
+    INIT: string;
+    START: string;
+    CALCULATING: string;
+    DONE: string;
+    ERROR: string;
+};

package/dist/core/constants.js

@@ -0,0 +1,48 @@
+// deck.gl-community
+// SPDX-License-Identifier: MIT
+// Copyright (c) vis.gl contributors
+import { MarkerList } 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 const NODE_STATE = {
+    DEFAULT: 'default',
+    HOVER: 'hover',
+    DRAGGING: 'dragging',
+    SELECTED: 'selected'
+};
+export const EDGE_STATE = {
+    DEFAULT: 'default',
+    HOVER: 'hover',
+    DRAGGING: 'dragging',
+    SELECTED: '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'
+};
+// edge shape
+export const EDGE_TYPE = {
+    SPLINE_CURVE: 'SPLINE_CURVE',
+    LINE: 'LINE',
+    PATH: 'PATH'
+};
+// decorators on edges
+export const EDGE_DECORATOR_TYPE = {
+    LABEL: 'EDGE_LABEL',
+    FLOW: 'FLOW'
+};
+// the status of the layout
+export const LAYOUT_STATE = {
+    INIT: 'INIT',
+    START: 'START',
+    CALCULATING: 'CALCULATING',
+    DONE: 'DONE',
+    ERROR: 'ERROR'
+};

package/dist/core/edge.d.ts

@@ -0,0 +1,86 @@
+import { Node } from './node';
+interface EdgeOptions {
+    id: string | number;
+    sourceId: string | number;
+    targetId: string | number;
+    directed?: boolean;
+    data: Record<string, unknown>;
+}
+export declare class Edge {
+    /** Unique uuid of the edge. */
+    id: string | number;
+    /** ID of the source node. */
+    private _sourceId;
+    /** ID of the target node. */
+    private _targetId;
+    /** Whether the edge is directed or not. */
+    private _directed;
+    /** Origin data reference of the edge. */
+    private _data;
+    /** Check the type of the object when picking engine gets it. */
+    readonly isEdge = true;
+    /** Nodes at either end of this edge. */
+    private readonly _connectedNodes;
+    /** Edge state. */
+    state: string;
+    /**
+     * The constructor
+     * @param  {String|Number} options.id - the unique ID of the edge
+     * @param  {String|Number} options.sourceId - the ID of the source node
+     * @param  {String|Number} options.targetId - the ID of the target node
+     * @param  {Boolean} options.directed - whether the edge is directed or not
+     * @param  {Record<string, unknown>} options.data - origin data reference
+     */
+    constructor({ id, sourceId, targetId, data, directed }: EdgeOptions);
+    /**
+     * Return the ID of the edge
+     * @return {String|Number} - the ID of the edge.
+     */
+    getId(): string | number;
+    /**
+     * Return whether the edge is directed or not.
+     * @return {Boolean} true if the edge is directed.
+     */
+    isDirected(): boolean;
+    /**
+     * Get the ID of the source node.
+     * @return {String|Number} the ID of the source node.
+     */
+    getSourceNodeId(): string | number;
+    /**
+     * Get the ID of the target node.
+     * @return {String|Number} the ID of the target node.
+     */
+    getTargetNodeId(): string | number;
+    /**
+     * Return of the value of the selected property key.
+     * @param  {String} key - property key.
+     * @return {Any} - the value of the property.
+     */
+    getPropertyValue(key: string): unknown;
+    /**
+     * Set the origin data as a reference.
+     * @param {Object} data - the origin data.
+     */
+    setData(data: Record<string, unknown>): void;
+    /**
+     * Update a data property.
+     * @param {String} key - the key of the property
+     * @param {Any} value - the value of the property.
+     */
+    setDataProperty(key: string, value: unknown): void;
+    /**
+     * Set edge state
+     * @param {String} state - one of EDGE_STATE
+     */
+    setState(state: string): void;
+    /**
+     * Get edge state
+     * @returns {string} state - one of EDGE_STATE
+     */
+    getState(): string;
+    addNode(node: Node): void;
+    removeNode(node: Node): void;
+    getConnectedNodes(): Node[];
+}
+export {};

package/dist/core/edge.js

@@ -0,0 +1,121 @@
+// deck.gl-community
+// SPDX-License-Identifier: MIT
+// Copyright (c) vis.gl contributors
+// Basic data structure of an edge
+import { EDGE_STATE } from './constants';
+export class Edge {
+    /** Unique uuid of the edge. */
+    id;
+    /** ID of the source node. */
+    _sourceId;
+    /** ID of the target node. */
+    _targetId;
+    /** Whether the edge is directed or not. */
+    _directed;
+    /** Origin data reference of the edge. */
+    _data;
+    /** Check the type of the object when picking engine gets it. */
+    isEdge = true;
+    /** Nodes at either end of this edge. */
+    _connectedNodes = {};
+    /** Edge state. */
+    state = EDGE_STATE.DEFAULT;
+    /**
+     * The constructor
+     * @param  {String|Number} options.id - the unique ID of the edge
+     * @param  {String|Number} options.sourceId - the ID of the source node
+     * @param  {String|Number} options.targetId - the ID of the target node
+     * @param  {Boolean} options.directed - whether the edge is directed or not
+     * @param  {Record<string, unknown>} options.data - origin data reference
+     */
+    constructor({ id, sourceId, targetId, data, directed = false }) {
+        this.id = id;
+        this._sourceId = sourceId;
+        this._targetId = targetId;
+        this._directed = directed;
+        this._data = data;
+    }
+    /**
+     * Return the ID of the edge
+     * @return {String|Number} - the ID of the edge.
+     */
+    getId() {
+        return this.id;
+    }
+    /**
+     * Return whether the edge is directed or not.
+     * @return {Boolean} true if the edge is directed.
+     */
+    isDirected() {
+        return this._directed;
+    }
+    /**
+     * Get the ID of the source node.
+     * @return {String|Number} the ID of the source node.
+     */
+    getSourceNodeId() {
+        return this._sourceId;
+    }
+    /**
+     * Get the ID of the target node.
+     * @return {String|Number} the ID of the target node.
+     */
+    getTargetNodeId() {
+        return this._targetId;
+    }
+    /**
+     * Return of the value of the selected property key.
+     * @param  {String} key - property key.
+     * @return {Any} - the value of the property.
+     */
+    getPropertyValue(key) {
+        // try to search the key within this object
+        if (this.hasOwnProperty(key)) {
+            return this[key];
+        }
+        // try to search the key in the original data reference
+        else if (this._data.hasOwnProperty(key)) {
+            return this._data[key];
+        }
+        // otherwise, not found
+        return undefined;
+    }
+    /**
+     * Set the origin data as a reference.
+     * @param {Object} data - the origin data.
+     */
+    setData(data) {
+        this._data = data;
+    }
+    /**
+     * Update a data property.
+     * @param {String} key - the key of the property
+     * @param {Any} value - the value of the property.
+     */
+    setDataProperty(key, value) {
+        this._data[key] = value;
+    }
+    /**
+     * Set edge state
+     * @param {String} state - one of EDGE_STATE
+     */
+    setState(state) {
+        this.state = state;
+    }
+    /**
+     * Get edge state
+     * @returns {string} state - one of EDGE_STATE
+     */
+    getState() {
+        return this.state;
+    }
+    addNode(node) {
+        this._connectedNodes[node.getId()] = node;
+    }
+    removeNode(node) {
+        delete this._connectedNodes[node.getId()];
+    }
+    getConnectedNodes() {
+        return Object.values(this._connectedNodes);
+    }
+}

package/dist/core/graph-engine.d.ts

@@ -0,0 +1,54 @@
+import { BaseLayout } from './base-layout';
+import { Edge } from './edge';
+import { Graph } from './graph';
+export declare class GraphEngine extends EventTarget {
+    private readonly _graph;
+    private readonly _layout;
+    private readonly _cache;
+    private _layoutDirty;
+    private _transactionInProgress;
+    constructor(graph: Graph, layout: BaseLayout);
+    /** Getters */
+    getNodes: () => Node[];
+    getEdges: () => Edge[];
+    getNodePosition: (node: any) => [number, number];
+    getEdgePosition: (edge: any) => {
+        type: string;
+        sourcePosition: number[];
+        targetPosition: number[];
+        controlPoints: any[];
+    };
+    getGraphVersion: () => number;
+    getLayoutLastUpdate: () => number;
+    getLayoutState: () => string;
+    /** Operations on the graph */
+    lockNodePosition: (node: any, x: any, y: any) => void;
+    unlockNodePosition: (node: any) => void;
+    /**
+     * @fires GraphEngine#onLayoutStart
+     */
+    _onLayoutStart: () => void;
+    /**
+     * @fires GraphEngine#onLayoutChange
+     */
+    _onLayoutChange: () => void;
+    /**
+     * @fires GraphEngine#onLayoutDone
+     */
+    _onLayoutDone: () => void;
+    /**
+     * @fires GraphEngine#onLayoutError
+     */
+    _onLayoutError: () => void;
+    _onGraphStructureChanged: (entity: any) => void;
+    _onTransactionStart: () => void;
+    _onTransactionEnd: () => void;
+    /** Layout calculations */
+    run: () => void;
+    clear: () => void;
+    resume: () => void;
+    stop: () => void;
+    _graphChanged: () => void;
+    _updateLayout: () => void;
+    _updateCache(key: any, updateValue: any): void;
+}