@neo4j-nvl/base 0.3.1-3ce43a8b

package/dist/base.mjs.LICENSE.txt

@@ -0,0 +1,10 @@
+/*! regenerator-runtime -- Copyright (c) 2014-present, Facebook, Inc. -- license (MIT): https://github.com/facebook/regenerator/blob/main/LICENSE */
+
+/**
+ * @license
+ * Lodash <https://lodash.com/>
+ * Copyright OpenJS Foundation and other contributors <https://openjsf.org/>
+ * Released under MIT license <https://lodash.com/license>
+ * Based on Underscore.js 1.8.3 <http://underscorejs.org/LICENSE>
+ * Copyright Jeremy Ashkenas, DocumentCloud and Investigative Reporters & Editors
+ */

package/dist/types/index.d.ts

@@ -0,0 +1,379 @@
+import type { ExternalCallbacks } from './modules/ExternalCallbackHandler';
+import type { ForceDirectedOptions, HierarchicalOptions, Layout, LayoutOptions, NodeBorderStyles, NvlOptions, NvlState, Renderer, ZoomOptions } from './modules/state';
+import { ForceDirectedLayoutType, FreeLayoutType, GridLayoutType, HierarchicalLayoutType, d3ForceLayoutType } from './modules/state';
+import { drawCircleBand } from './renderers/canvasrenderer/util';
+import type { Node, PartialNode, PartialRelationship, Relationship } from './types/graph-element';
+import { CompatibilityError } from './utils/errors';
+import type { Point } from './utils/geometry';
+import type { HitTargetNode, HitTargetRelationship, HitTargets } from './utils/hittest';
+/**
+ * Extends the MouseEvent interface with the {@link HitTargets} property.
+ * The result of a _.{@link NVL.getHits} call.
+ */
+interface NvlMouseEvent extends MouseEvent {
+    nvlTargets: HitTargets;
+}
+/**
+ * Class for a NVL instance.
+ * @example
+ * This is a basic setup for a NVL instance.
+ * ```js
+ * const nodes = [
+ *   { id: '1', label: 'Node 1', color: '#e04141' },
+ *   { id: '2', label: 'Node 2', color: '#e09c41' }
+ * ]
+ * const relationships = [
+ *   { id: '12', from: '1', to: '2' }
+ * ]
+ * const options = {
+ *   layout: 'hierarchical',
+ *   initialZoom: 0.5
+ * }
+ * const callbacks = {
+ *   onLayoutDone: () => console.log('Layout done')
+ * }
+ * const nvl = new NVL(document.getElementById('frame'), nodes, relationships, options, callbacks)
+ * ```
+ */
+declare class NVL {
+    private readonly externalCallbackHandler;
+    private readonly performance;
+    private visState;
+    private nvlController;
+    private options;
+    /**
+     * Creates a new NVL instance.
+     * @constructor
+     * @param {HTMLElement} frame - The DOM element to display the graph in
+     * @param {Node[]} nvlNodes - An Array of nodes
+     * @param {Relationship[]} nvlRels - An Array of relationships
+     * @param {NvlOptions} options - Options for the NVL instance
+     * @param {ExternalCallbackHandler} callbacks - Callbacks triggered on NVL events
+     */
+    constructor(frame: HTMLElement, nvlNodes?: Node[], nvlRels?: Relationship[], options?: NvlOptions, callbacks?: ExternalCallbacks);
+    /**
+     * Restarts the NVL instance.
+     * @param {NvlOptions} options - new options for the NVL instance
+     * @param {boolean} retainPositions - whether or not to retain the current node positions
+     * @note new options will be merged with current options
+     */
+    restart(options?: NvlOptions, retainPositions?: boolean): void;
+    /**
+     * Adds nodes and relationships to NVL and updates existing nodes and relationships.
+     * @param {Node[] | PartialNode[]} nodes - An Array of nodes to be added or updated
+     * @param {Relationship[] | PartialRelationship[]} relationships - An Array of relationships to be added or updated
+     * @note To update nodes or relationships, they must have an id that matches the id of the
+     * node or relationship to be updated.
+     * @note Only the properties that are provided will be updated.
+     * If an existing property is not provided, it will not be changed.
+     * @example
+     * Adding and updating nodes and relationships
+     * ```js
+     * const nodes = [
+     * { id: '1', label: 'Node 1', color: '#e04141' },
+     * { id: '2', label: 'Node 2', color: '#e09c41' }
+     * ]
+     * const relationships = [
+     * { id: '12', from: '1', to: '2' }
+     * ]
+     * // Adds new nodes and relationships
+     * nvl.addAndUpdateElementsInGraph(nodes, relationships)
+     * // Updates an existing relationship
+     * nvl.addAndUpdateElementsInGraph([], [{ id: '12', color: '#e0df41' }])
+     * ```
+     */
+    addAndUpdateElementsInGraph(nodes?: Node[] | PartialNode[], relationships?: Relationship[] | PartialRelationship[]): void;
+    /**
+     * Gets the currently selected nodes.
+     * @returns {(Node & Point)[]} An array of all currently selected nodes and their positions.
+     */
+    getSelectedNodes(): (Node & Point)[];
+    /**
+     * Gets the currently selected relationships.
+     * @returns {Relationship[]} An array of all currently selected relationships.
+     */
+    getSelectedRelationships(): Relationship[];
+    /**
+     * Updates relationships in the current scene with the provided array of nodes and relationships.
+     * @param {Node[] | PartialNode[]} nodes The updated nodes.
+     * @param {Relationship[] | PartialRelationship[]} relationships The updated relationships.
+     * @note ignores any nodes or relationships that do not exist in the current scene.
+     * @note To update nodes or relationships, they must have an id that matches the id of the
+     * node or relationship to be updated.
+     * @note Only the properties that are provided will be updated.
+     * If an existing property is not provided, it will not be changed.
+     * @example
+     * Updating nodes and relationships
+     * ```js
+     * const nodes = [
+     * { id: '1', label: 'Node 1', color: '#e04141' },
+     * { id: '2', label: 'Node 2', color: '#e09c41' }
+     * ]
+     * const relationships = [
+     * { id: '12', from: '1', to: '2' }
+     * ]
+     * const nvl = new NVL(container, nodes, relationships)
+     * // Updates an existing node and relationship
+     * nvl.updateElementsInGraph([{ id: '1', selected: true }], [{ id: '12', color: '#e0df41' }])
+     * ```
+     */
+    updateElementsInGraph(nodes: Node[] | PartialNode[], relationships: Relationship[] | PartialRelationship[]): void;
+    /**
+     * Adds nodes and relationships in the current scene.
+     * @param {Node[]} nodes The nodes to be added.
+     * @param {Relationship[]} relationships The relationships to be added.
+     */
+    addElementsToGraph(nodes: Node[], relationships: Relationship[]): void;
+    /**
+     * Removes the specified nodes from the current scene.
+     * @param {string[]} nodeIds The node ids to be removed.
+     * @note adjacent relationships will also be removed.
+     */
+    removeNodesWithIds(nodeIds: string[]): void;
+    /**
+     * Removes the specified relationships from the current scene.
+     * @param {string[]} relationshipIds The relationship ids to be removed.
+     */
+    removeRelationshipsWithIds(relationshipIds: string[]): void;
+    /**
+     * Returns the node data that is currently stored in the visualisation for a given id.
+     * @param {string} id The id of the node that should be returned.
+     * @returns {Node} The node or undefined if there is no node with the given id.
+     */
+    getNodes(): Node[];
+    /**
+     * Returns the relationships that are currently in the visualization.
+     * @returns {Relationship[]} An array of the relationships in the visualization.
+     */
+    getRelationships(): Relationship[];
+    /**
+     * Returns the node data that is currently stored in the visualisation for a given id.
+     * @param {string} id The id of the node that should be returned.
+     * @returns {Node} The node or undefined if there is no node with the given id.
+     */
+    getNodeById(id: string): Node;
+    /**
+     * Returns the relationship data that is currently stored in the visualisation for a given id.
+     * @param {string} id The id of the relationship that should be returned.
+     * @returns {Relationship} The relationship or undefined if there is no relationship with the given id.
+     */
+    getRelationshipById(id: string): Relationship;
+    /**
+     * Returns the node position that is currently stored in the visualisation for a given id.
+     * @param {string} id The id of the node position that should be returned.
+     * @returns {Node} The position information for the given id, or undefined if there is no such node
+     * or the layout has not yet run with that node.
+     */
+    getPositionById(id: string): Node;
+    /**
+     * Returns the current options.
+     * @returns {NvlOptions} The current options.
+     * @internal
+     */
+    getCurrentOptions(): NvlOptions;
+    /** Removes the graph visualization from the DOM and cleans up everything. */
+    destroy(): void;
+    /**
+     * De-selects all nodes and relationships.
+     */
+    deselectAll(): void;
+    /**
+     * Updates pan and zoom fit the specified nodes in the viewport.
+     * @param {string[]} nodeIds The ids of the nodes to fit on the screen,
+     * @param {NvlState['zoomOptions']} zoomOptions specific options on how to transition the zoom
+     * @note If the zoom level required to fit the provided nodes is outside of the range provided by the
+     * {@link NvlOptions.minZoom} and {@link NvlOptions.maxZoom} options,
+     * and {@link NvlOptions.allowDynamicMinZoom} is set to `false`,
+     * the zoom level will be set to the closest valid zoom level,
+     * even if the given nodes do not fit the viewport yet.
+     */
+    fit(nodeIds: string[], zoomOptions: NvlState['zoomOptions']): void;
+    /**
+     * Resets the zoom of the viewport back to the default zoom level of 0.75
+     */
+    resetZoom(): void;
+    /**
+     * Toggles between the WebGL and Canvas rendering.
+     * @deprecated use {@link setRenderer} instead.
+     * @param {boolean} enabled Whether or not WebGL renderer should be used.
+     * @internal
+     */
+    setUseWebGLRenderer(enabled: boolean): void;
+    /**
+     * Switches between rendering methods
+     * @param renderer - which rendering method to use
+     */
+    setRenderer(renderer: string): void;
+    /**
+     * Restarts NVL with or without WebGL support.
+     * @param {boolean} disabled Whether or not WebGL should be disabled.
+     * @note not to be confused with {@link setUseWebGLRenderer}, which only affects the rendering method
+     * @experimental
+     * @internal
+     */
+    setDisableWebGL(disabled?: boolean): void;
+    /**
+     * Pins the specified node so it is not affected by layout forces.
+     * @param {string} nodeId The id of the node to be pinned.
+     */
+    pinNode(nodeId: string): void;
+    /**
+     * Un-pins the specified nodes so it is affected by layout forces again.
+     * @param {string[]} nodeIds The ids of the nodes to be un-pinned.
+     */
+    unPinNode(nodeIds: string[]): void;
+    /**
+     * Changes the layout type.
+     * @param {Layout} layout The layout type.
+     */
+    setLayout(layout: Layout): void;
+    /**
+     * Updates the configuration of the current layout.
+     * @param {LayoutOptions} options The layout configuration.
+     */
+    setLayoutOptions(options: LayoutOptions): void;
+    /**
+     * Returns the nodes that are currently in the visualization.
+     * @note The `rels` property of the returned object is always empty.
+     * @returns {{ nodes: Node[], rels: Relationship [] }} An array of the nodes in the visualization.
+     */
+    getNodesOnScreen(): {
+        nodes: Node[];
+        rels: Relationship[];
+    };
+    /**
+     * Fetches and returns the current positions of all nodes as an array of coordinates.
+     * @returns {(Node & Point)[]} An array of node positions.
+     */
+    getNodePositions(): (Node & Point)[];
+    /**
+     * Sets the node positions based on data provided
+     * @param {Node[]} data The positions that the nodes should be set to.
+     * @param {boolean} updateLayout whether or not the current layout algorithm
+     * should update the graph after setting the node positions.
+     * False by default.
+     */
+    setNodePositions(data: Node[], updateLayout?: boolean): void;
+    /**
+     * Checks and returns whether the current layout is still in flux.
+     * @returns {boolean} Whether or not the layout is moving.
+     */
+    isLayoutMoving(): boolean;
+    /**
+     * Saves the current view of the graph visualization canvas as a png to the client.
+     * @param {{ filename: string, backgroundColor: string }} options The filename and background color of the png.
+     * @param {string} options.filename The filename of the png file.
+     * @param {string} options.backgroundColor - The background color of the png file.
+     * @note The size of the png file will be the size of the canvas in the DOM.
+     */
+    saveToFile(options: {
+        filename?: string;
+        backgroundColor?: string;
+    }): void;
+    /**
+     * Saves the entire graph visualization canvas as a png to the client.
+     * @param {{ filename: string, backgroundColor: string }} options The filename and background color of the png.
+     * @param {string} options.filename The filename of the png file.
+     * @param {string} options.backgroundColor - The background color of the png file.
+     * @note The size of the png file will be as large as the entire graph at the default zoom level.
+     * Can result in a very large file.
+     * @example
+     * // Save the entire graph visualization canvas as a png to the client.
+     * graphVisualization.saveFullGraphToFile({ filename: 'graph.png', backgroundColor: '#fff' })
+     */
+    saveFullGraphToLargeFile(options: {
+        filename?: string;
+        backgroundColor?: string;
+    }): void;
+    /**
+     * Sets the zoom of the viewport to a specific value.
+     * @param {number} absolute The desired zoom level.
+     * @note When updating both the zoom level and pan coordinates,
+     * use {@link setZoomAndPan} instead of calling {@link setZoom} and {@link setPan}
+     * separately to avoid jittering.
+     * @note If the zoom level is outside of the range provided by the
+     * {@link NvlOptions.minZoom} and {@link NvlOptions.maxZoom} options,
+     * the zoom level will be set to the closest valid zoom level.
+     * @note If {@link NvlOptions.allowDynamicMinZoom} is set to true,
+     * the {@link NvlOptions.minZoom} option will be ignored of the current graph does not fit the viewport.
+     */
+    setZoom(absolute: number): void;
+    /**
+     * Sets the zoom of the viewport to a specific value.
+     * @param {number} panX The desired panX value.
+     * @param {number} panY The desired panY value.
+     * @note When updating both the zoom level and pan coordinates,
+     * use {@link setZoomAndPan} instead of calling {@link setZoom} and {@link setPan}
+     * separately to avoid jittering.
+     */
+    setPan(panX: number, panY: number): void;
+    /**
+     * Sets the zoom and pan of the viewport to specific values.
+     * @param {number} zoom The desired zoom level.
+     * @param {number} panX The desired panX value.
+     * @param {number} panY The desired panY value.
+     * @note When only updating the zoom level or pan coordinates, use {@link setZoom} or {@link setPan} instead.
+     * @note If the zoom level is outside of the range provided by the
+     * {@link NvlOptions.minZoom} and {@link NvlOptions.maxZoom} options,
+     * the zoom level will be set to the closest valid zoom level.
+     * @note If {@link NvlOptions.allowDynamicMinZoom} is set to true,
+     * the {@link NvlOptions.minZoom} option will be ignored of the current graph does not fit the viewport.
+     */
+    setZoomAndPan(zoom: number, panX: number, panY: number): void;
+    /**
+     * Get the current zoom level of the viewport.
+     * @returns {number} The current zoom level
+     */
+    getScale(): number;
+    /**
+     * Returns the current pan of the viewport.
+     * @returns {Point} The current pan of the viewport.
+     */
+    getPan(): Point;
+    /**
+     * Gets the nodes and relationships that have been hit by a pointer event.
+     * @param evt The mouse event.
+     * @param targets The graph elements to check for hits. Defaults to ['node', 'relationship'].
+     * @param hitOptions - Options for the hit test.
+     * @returns A {@link NvlMouseEvent} with the {@link HitTargets} property
+     * containing the nodes and relationships that have been hit by the pointer event.
+     *
+     * @example
+     * ```js
+     * const container = document.getElementById('frame')
+     * const nvl = new NVL(container, nodes, relationships)
+     *
+     * // Get the nodes and relationships that have been hit by a pointer event.
+     * container.addEventListener('click', (evt) => {
+     *   const { nvlTargets } = nvl.getHits(evt)
+     *   console.log('clicked elements:', nvlTargets)
+     * })
+     * ```
+     */
+    getHits(evt: MouseEvent, targets?: ('node' | 'relationship')[], hitOptions?: {
+        hitNodeMarginWidth: number;
+    }): NvlMouseEvent;
+    /**
+     * Provides the container DOM element the graph is rendered in.
+     * @returns The container element of the NVL instance.
+     */
+    getContainer(): HTMLElement;
+    private initialise;
+    private setupLogging;
+    private nodeRemoval;
+    private edgeRemoval;
+    private update;
+    private validateNodes;
+    private validateRelationships;
+    private checkWebGLCompatibility;
+}
+/**
+ * Functions for mapping colors.
+ * @internal
+ */
+declare const colorMapperFunctions: {
+    textColorForBackground: (color: string) => string;
+};
+export default NVL;
+export type { NvlOptions, Renderer, Node, Relationship, PartialNode, PartialRelationship, Layout, LayoutOptions, ForceDirectedOptions, HierarchicalOptions, ExternalCallbacks, HitTargets, HitTargetNode, HitTargetRelationship, Point, NvlMouseEvent, NodeBorderStyles, ZoomOptions };
+export { NVL, colorMapperFunctions, CompatibilityError, ForceDirectedLayoutType, HierarchicalLayoutType, GridLayoutType, FreeLayoutType, d3ForceLayoutType, drawCircleBand };

package/dist/types/layouts/animatedlayout/AnimatedLayout.d.ts

@@ -0,0 +1,25 @@
+import type { NvlState } from '../../modules/state';
+import type { Node } from '../../types/graph-element';
+export default class AnimatedLayout {
+    positions: Record<string, Node>;
+    oldPositions: Record<string, Node>;
+    startTime: number;
+    t: number;
+    currentT: number;
+    state: NvlState;
+    shouldUpdateAnimator: boolean;
+    parents: Record<string, string>;
+    animationCompleteCallback: () => void;
+    shouldUpdate: boolean;
+    constructor(config: {
+        state: NvlState;
+        animationCompleteCallback?: () => void;
+    });
+    private getPositionMapFromState;
+    updatePositionsFromState(): void;
+    updateOldPositionFromState(): void;
+    startAnimation(): void;
+    update(): void;
+    updateNodes(positionList: Node[]): void;
+    getNodePositions(nodeList: Node[]): Node[];
+}

package/dist/types/layouts/animatedlayout/animationUtils.d.ts

@@ -0,0 +1,9 @@
+import type { Node } from '../../types/graph-element';
+import type { Point } from '../../utils/geometry';
+/**
+ * Calculates the average node coordinates for a given set of nodes.
+ * @param {Node[]} nodes The nodes to calculate the average position for.
+ * @param {Record<string, Node | Point>} positions The positions of the nodes.
+ * @returns {number[]} The average node coordinates.
+ */
+export declare const calculateAverageNodePosition: (nodes: Node[], positions: Record<string, Node | Point>) => number[];

package/dist/types/layouts/d3forcelayout/circularLayout.d.ts

@@ -0,0 +1,5 @@
+import type { D3Node } from './types';
+export declare function circularLayout(nodes: D3Node[], center: {
+    x: number;
+    y: number;
+}, radius: number): void;

package/dist/types/layouts/d3forcelayout/constants.d.ts

@@ -0,0 +1,18 @@
+import type { SimulationLinkDatum } from 'd3-force';
+import type { D3Node } from './types';
+export declare const VELOCITY_DECAY = 0.4;
+export declare const DEFAULT_ALPHA = 1;
+export declare const DEFAULT_ALPHA_TARGET = 0;
+export declare const DEFAULT_ALPHA_MIN = 0.05;
+export declare const DRAGGING_ALPHA = 0.2;
+export declare const MAX_PRECOMPUTED_TICKS = 200;
+export declare const MAX_STABILIZE_TICKS = 100;
+export declare const LINK_DISTANCE = 45;
+export declare const BARNES_HUT_THETA = 1.2;
+export declare const FORCE_LINK_DISTANCE: (relationship: SimulationLinkDatum<D3Node>) => number;
+export declare const FORCE_COLLIDE_RADIUS: (node: D3Node) => number;
+export declare const LAYOUT_RADIUS: (numberOfNodes: number) => number;
+export declare const FORCE_CHARGE: () => number;
+export declare const FORCE_CHARGE_START: () => number;
+export declare const FORCE_CENTER_X = 0.03;
+export declare const FORCE_CENTER_Y = 0.03;

package/dist/types/layouts/d3forcelayout/d3ForceLayout.d.ts

@@ -0,0 +1,29 @@
+export class d3ForceLayout {
+    constructor(config: any);
+    state: any;
+    d3Nodes: {};
+    d3RelList: {};
+    computing: boolean;
+    center: {
+        x: number;
+        y: number;
+    };
+    simulation: import("d3-force").Simulation<import("d3-force").SimulationNodeDatum, undefined>;
+    simulationStopped: boolean;
+    shouldUpdate: boolean;
+    stateDisposers: any[];
+    setOptions(options: any): void;
+    updateNodes(positionList: any): void;
+    update(refreshPositions?: boolean): void;
+    layout(_nodes: any, _rels: any, firstTimeAddingNodes: any): void;
+    getNodePositions(nodeList: any): {
+        id: any;
+        x: any;
+        y: any;
+    }[];
+    getShouldUpdate(): boolean;
+    getComputing(): boolean;
+    terminateUpdate(): void;
+    destroy(): void;
+    setAlpha(alpha: any): void;
+}

package/dist/types/layouts/d3forcelayout/types.d.ts

@@ -0,0 +1,9 @@
+export type D3Node = {
+    x: number | undefined;
+    y: number | undefined;
+    vx?: number;
+    vy?: number;
+    fx?: number | null;
+    fy?: number | null;
+    size?: number;
+};

package/dist/types/layouts/forcedirectedlayout/ForceCytoLayout.d.ts

@@ -0,0 +1,24 @@
+export const ForceDirectedLayoutType: "forceDirected";
+export const CoseBilkentType: "coseBilkent";
+export class ForceCytoLayout {
+    constructor(config: any);
+    isCytoscapeEnabled: any;
+    _physLayout: PhysLayout;
+    _coseBilkentLayout: CoseBilkentLayout;
+    _currentLayout: PhysLayout;
+    _currentLayoutType: string;
+    _state: any;
+    setOptions(options: any): void;
+    _getLayout(layoutType: any): CoseBilkentLayout | PhysLayout;
+    _setLayout(layoutType: any): void;
+    copyLayoutPositions(nodeList: any, prevLayout: any, nextLayout: any): void;
+    update(refreshPositions?: boolean): void;
+    getShouldUpdate(): boolean;
+    getComputing(): boolean;
+    updateNodes(positionList: any): void;
+    getNodePositions(data: any): any[];
+    terminateUpdate(): void;
+    destroy(): void;
+}
+import { PhysLayout } from './physlayout/PhysLayout';
+import { CoseBilkentLayout } from './cosebilkentlayout/CoseBilkentLayout';

package/dist/types/layouts/forcedirectedlayout/cosebilkentlayout/CoseBilkentLayout.d.ts

@@ -0,0 +1,32 @@
+import type { NvlState } from '../../../modules/state';
+import type { Node, Relationship } from '../../../types/graph-element';
+import AnimatedLayout from '../../animatedlayout/AnimatedLayout';
+type LayoutData = {
+    elements: {
+        group: string;
+        data: {
+            id: string;
+        };
+    }[];
+    spacingFactor: number;
+};
+export declare class CoseBilkentLayout extends AnimatedLayout {
+    private stateDisposers;
+    cytoCompleteCallback: () => void;
+    computing: boolean;
+    pendingLayoutData: LayoutData;
+    worker: SharedWorker;
+    constructor(config: {
+        state: NvlState;
+        cytoCompleteCallback?: () => void;
+        animationCompleteCallback?: () => void;
+    });
+    setOptions(options: any): void;
+    update(refreshPositions?: boolean, updateMobXNodes?: Node[], updateMobXRelationships?: Relationship[]): void;
+    getShouldUpdate(): boolean;
+    getComputing(): boolean;
+    layout(nodes: Node[], relationships: Relationship[]): void;
+    terminateUpdate(): void;
+    destroy(): void;
+}
+export {};