@neo4j-nvl/base 0.3.1-016e1c20

package/dist/types/modules/performance.d.ts

@@ -0,0 +1,93 @@
+/**
+ * A class capable of measuring performance.
+ * Usage:
+ * When you want to measure a block of code, start by calling
+ * performanceTesterInstance.startTest() or
+ * performanceTesterInstance.startTest('Some readable name') if you
+ * want to control how it prints.
+ * After the block of code ends, call performanceTesterInstance.endTest()
+ */
+export default class PerformanceTester {
+    disabled: boolean;
+    tree: PerformanceTree;
+    /**
+     * Starts a performance measurement. Every call to this method must be followed
+     * by a call to endTest(). Tests can be nested.
+     * @param  {String} name String identifying this measurement. Only used for printing, so
+     *                       keep it human readable.
+     */
+    startTest(name: string): void;
+    /**
+     * Ends the last started test, giving it an end time.
+     */
+    endTest(): void;
+    /**
+     * Clears all performance measurements
+     */
+    reset(): void;
+    /**
+     * Prints all the performance measurements to console by calling
+     * print() on the performance tree.
+     */
+    print(): void;
+}
+/**
+ * A tree of PerformanceTreeNodes.
+ * @type {PerformanceTree}
+ */
+declare class PerformanceTree {
+    root: any;
+    current: any;
+    /**
+     * Empties the tree.
+     */
+    clear(): void;
+    /**
+     * Adds a new node to the tree at the current open position, containing the
+     * data provided. It also sets the newly added node as the currently open one.
+     * @param {PerformanceData} data A PerformanceData object.
+     */
+    add(data: PerformanceData): void;
+    /**
+     * The tree always maintains a pointer to the currently open node. This
+     * method closes that node, closes the data object in contains, and opens
+     * the parent node.
+     */
+    close(): void;
+    /**
+     * Gets the data object of the currently open node.
+     * @return {PerformanceData} The data object of the currently open node.
+     */
+    getCurrentData(): PerformanceData;
+    /**
+     * Prints this entire tree to the console.
+     */
+    print(): void;
+}
+/**
+ * Performance measurement data.
+ * @type {PerformanceData}
+ */
+declare class PerformanceData {
+    /**
+     * Instantiates a data measurement, giving it the start time when constructor is called.
+     * Remember that you also have to call close on this object to make it valid.
+     * @param  {String} name String identifying this measurement. Only used for printing, so
+     *                       keep it human readable.
+     * @return {PerformanceData} The data object
+     */
+    constructor(name: string);
+    name: any;
+    startTime: any;
+    endTime: any;
+    /**
+     * Sets the endTime measurement on this data object.
+     */
+    close(): void;
+    /**
+     * Gets the time spent on this measurement
+     * @return {Number} Time spent in ms
+     */
+    _timeSpent(): number;
+}
+export {};

package/dist/types/modules/state.d.ts

@@ -0,0 +1,242 @@
+import type { LogLevelDesc } from 'loglevel';
+import type { WaypointPath } from '../renderers/canvasrenderer/types';
+import type { ExternalCallbacks } from './ExternalCallbackHandler';
+import type { NodeDataSet, RelationshipDataSet } from './dataset';
+type RingStyle = {
+    width?: number;
+    widthFactor?: number;
+    color: string;
+};
+export type ShadowStyle = {
+    width: number;
+    opacity: number;
+    color: string;
+};
+export type BorderStyle = {
+    rings?: RingStyle[];
+    shadow?: ShadowStyle;
+};
+/**
+ * @internal
+ */
+export type BorderStyles = {
+    selected: BorderStyle;
+    default: BorderStyle;
+};
+export declare const RelationshipBorderStyles: BorderStyles;
+/** The default zoom level in a graph when not specified otherwise. */
+export declare const DefaultZoomLevel = 0.75;
+/**
+ * The options for the force directed layout
+ */
+export interface ForceDirectedOptions {
+    /**
+     * @internal
+     */
+    gravity?: number;
+    /**
+     * @internal
+     */
+    intelWorkaround?: boolean;
+    /**
+     * @internal
+     */
+    isCytoscapeEnabled: boolean;
+    /**
+     * @internal
+     */
+    simulationStopVelocity?: number;
+}
+/**
+ * The options for the hierarchical layout
+ */
+export interface HierarchicalOptions {
+    /** The direction in which the layout should be oriented */
+    direction?: 'up' | 'down' | 'left' | 'right';
+    /** The packing method to be used */
+    packing?: 'bin' | 'stack';
+}
+/**
+ * The name of the force directed layout
+ */
+export declare const ForceDirectedLayoutType = "forceDirected";
+/**
+ * The name of the hierarchical layout
+ */
+export declare const HierarchicalLayoutType = "hierarchical";
+/**
+ * The name of the grid layout
+ * @internal
+ */
+export declare const GridLayoutType = "grid";
+/**
+ * The name of the free layout
+ * @internal
+ */
+export declare const FreeLayoutType = "free";
+/**
+ * The name of the d3 force layout
+ * @internal
+ */
+export declare const d3ForceLayoutType = "d3Force";
+export declare const WebGLRendererType = "webgl";
+export declare const CanvasRendererType = "canvas";
+/**
+ * The different types of layouts available
+ */
+export type Layout = typeof ForceDirectedLayoutType | typeof HierarchicalLayoutType | typeof GridLayoutType | typeof FreeLayoutType | typeof d3ForceLayoutType;
+export type LayoutOptions = ForceDirectedOptions & HierarchicalOptions;
+/**
+ * The different types of renderers available
+ */
+export type Renderer = typeof WebGLRendererType | typeof CanvasRendererType;
+/** Configurations for a NVL instance */
+export interface NvlOptions {
+    /**
+     * @internal
+     * Id for uniquely identifying the instance of Nvl
+     */
+    instanceId?: string;
+    /** The graph layout algorithm to be used */
+    layout?: Layout;
+    /**
+     * The minimum zoom level allowed
+     * @default 0.075
+     */
+    minZoom?: number;
+    /**
+     * The maximum zoom level allowed
+     * @default 10
+     */
+    maxZoom?: number;
+    /**
+     * Whether or not to dynamically allow decreasing minimum zoom value
+     * if current graph does not fit on screen at minimum zoom.
+     * @note When set to true, zoom and fit operations will allow zooming out
+     * further than the minimum zoom value if the graph does not fit on screen.
+     * When set to false, zoom and fit operations will stop at the minimum zoom value,
+     * even if the full graph does not fit on screen at that zoom level.
+     * @default true
+     */
+    allowDynamicMinZoom?: boolean;
+    /**
+     * @internal
+     * @deprecated
+     * The DOM element in which to render the graph visualization
+     */
+    frame?: HTMLElement;
+    /** The DOM container in which to render the minimap */
+    minimapContainer?: HTMLElement;
+    /** Configuration for the current layout */
+    layoutOptions?: LayoutOptions;
+    /** X-coordinate for panning of the current viewport */
+    panX?: number;
+    /** Y-coordinate for panning of the current viewport */
+    panY?: number;
+    /** Zoom value of the current viewport */
+    initialZoom?: number;
+    /**
+     * @deprecated use {@link renderer} instead
+     * Whether to user the Canvas or WebGL renderer
+     * @note will be ignored when {@link renderer} is set
+     */
+    useWebGL?: boolean;
+    /** What renderer to use */
+    renderer?: Renderer;
+    /**
+     * @internal
+     * Whether or not to disable WebGL completely.
+     */
+    disableWebGL?: boolean;
+    /**
+     * @internal
+     * Specify the log level.
+     */
+    logging?: {
+        level: LogLevelDesc;
+    };
+    /**
+     * @internal
+     */
+    relationshipThreshold?: number;
+    callbacks?: ExternalCallbacks;
+    /** The color to use for the default border of nodes */
+    nodeDefaultBorderColor?: string;
+    /** The color to use for the selected border of nodes */
+    selectedBorderColor?: string;
+    /**
+     * @internal
+     * @experimental
+     * Defines a time limit for how long layout iterations may run
+     */
+    layoutTimeLimit?: number;
+}
+/** Options that influence how fit-to-zoom should behave */
+export type ZoomOptions = {
+    /** If true, will zoom out to fit the specified nodes without changing the pan of the viewport. */
+    noPan?: boolean;
+    /** If true, will only zoom out if specified nodes won't fit into viewport but won't zoom in any further. */
+    outOnly?: boolean;
+    /** The minimum zoom value for the fit-to-zoom operation. */
+    minZoom?: number;
+    /** The maximum zoom value for the fit-to-zoom operation. */
+    maxZoom?: number;
+};
+export interface NvlState {
+    zoom: number;
+    zoomOptions: ZoomOptions;
+    minimapZoom: number;
+    defaultZoomLevel: number;
+    panX: number;
+    panY: number;
+    minimapPanX: number;
+    minimapPanY: number;
+    fitNodeIds: string[];
+    resetZoom: boolean;
+    forceWebGL: boolean;
+    webGLVisible: boolean;
+    renderer: Renderer;
+    disableWebGL: boolean;
+    fitMovement: number;
+    layout: Layout;
+    layoutOptions: LayoutOptions;
+    maxNodeRadius: number;
+    maxDistance: number;
+    minZoom: number;
+    maxZoom: number;
+    minMinimapZoom: number;
+    maxMinimapZoom: number;
+    nodes: NodeDataSet;
+    rels: RelationshipDataSet;
+    graphUpdates: number;
+    waypoints: {
+        data: Record<string, WaypointPath>;
+        counter: number;
+    };
+    setGraphUpdated: Function;
+    setRenderer: Function;
+    setWaypoints: Function;
+    setZoomPan: Function;
+    setZoom: (zoom: number, rect: HTMLElement) => void;
+    setPan: Function;
+    setLayout: Function;
+    setLayoutOptions: Function;
+    fitNodes: Function;
+    setZoomReset: Function;
+    clearFit: Function;
+    clearReset: Function;
+    updateZoomToFit: Function;
+    updateMinimapZoomToFit: Function;
+    autorun: Function;
+    reaction: Function;
+    nodeBorderStyles: BorderStyles;
+    relationshipBorderStyles: BorderStyles;
+}
+/**
+ * Create a new NVL state
+ *
+ * @param {NvlOptions} options - The options for the new state
+ * @returns {NvlState} - The state object
+ */
+export declare const createState: (options: NvlOptions) => NvlState;
+export {};

package/dist/types/renderers/canvasrenderer/Animation.d.ts

@@ -0,0 +1,64 @@
+/**
+ * Animation class to animate a value from a start value to an end value
+ */
+export declare class Animation {
+    /** The id of the element to animate */
+    readonly elementId: string;
+    /** The current value of the animation */
+    currentValue: number;
+    /** The start value of the animation */
+    private startValue;
+    /** The current time of the animation */
+    private currentTime;
+    /** The duration of the animation */
+    private duration;
+    /** The status of the animation */
+    private status;
+    /** The end value of the animation */
+    private endValue;
+    /** The start time of the animation */
+    private startTime;
+    /** The end time of the animation */
+    private endTime;
+    /** Flag to indicate if there is a next animation */
+    private hasNextAnimation;
+    /**
+     * Constructor
+     * @param {string} elementId The id of the element to animate.
+     * @param {number} startValue The start value of the animation.
+     */
+    constructor(elementId: string, startValue: number);
+    /**
+     * Sets the duration of the animation
+     * @param {number} duration The duration of the animation.
+     * @returns {void}
+     * @public
+     */
+    setDuration(duration: number): void;
+    /**
+     * Returns the status of the animation
+     * @returns {number} The status of the animation.
+     * @public
+     */
+    getStatus(): number;
+    /**
+     * Advances the animation to the next frame
+     * @returns {boolean} True if there is a next animation, false otherwise.
+     * @public
+     */
+    advance(): boolean;
+    /**
+     * Sets the end value of the animation
+     * @param {number} targetValue The end value of the animation.
+     * @returns {void}
+     * @public
+     */
+    setEndValue(targetValue: number): void;
+    /**
+     * Sets the end time of the animation
+     * @param {number} newEndTime The end time of the animation.
+     * @returns {void}
+     * @private
+     */
+    private setEndTime;
+}

package/dist/types/renderers/canvasrenderer/AnimationHandler.d.ts

@@ -0,0 +1,72 @@
+import { Animation } from './Animation';
+/**
+ * A small animation running engine that lets elements do any transitions and
+ * ask the rendered to redraw as long as needed.
+ * The object is owned by the canvas renderer
+ */
+export default class AnimationHandler {
+    /** A map of all animations */
+    private readonly animations;
+    /** A map of all durations */
+    private readonly durations;
+    /** The default duration */
+    private readonly defaultDuration;
+    /** Flag to indicate if a rerun is needed */
+    private hasNextAnimation;
+    /** Flag to indicate if animations should be ignored */
+    private ignoreAnimationsFlag;
+    constructor();
+    /**
+     * Main function run once per frame to advance all animations
+     * @returns {boolean} true if any animation is still running
+     */
+    advance(): boolean;
+    /**
+     * Sets a flag if animations should be ignored.
+     * If set to true all animations always return their end value.
+     * @param {boolean} shouldIgnore
+     */
+    ignoreAnimations(shouldIgnore: boolean): void;
+    /**
+     * Sets the duration for all animations
+     * @param {Object} options - An object containing animation durations for fade and size
+     */
+    setOptions(options: {
+        fadeDuration: number;
+        sizeDuration: number;
+    }): void;
+    /**
+     * Returns whether any animation is running
+     * @returns {boolean}
+     */
+    needsToRun(): boolean;
+    /**
+     * Returns the current value of an animation
+     * @param {string} elementId - The id of the element the animation is running on
+     * @param {string} name - The name of the animation
+     * @returns {number} The current value of the animation
+     */
+    getValueForAnimationName(elementId: string, name: string, target: number, type?: number): number;
+    private createAnimation;
+    getById(id: string): Record<string, Animation> | undefined;
+    /**
+     * Creates a new size animation for the given element and name.
+     * If an animation already exists for the given element and name, it will be returned.
+     * If not, a new animation will be created.
+     * @param {number} currentValue - The current value of the animation
+     * @param {string} elementId - The id of the element to animate
+     * @param {string} name - The name of the animation
+     * @returns {Animation} The animation
+     */
+    private createFadeAnimation;
+    /**
+     * Creates a new fade animation for the given element and name.
+     * If an animation already exists for the given element and name, it will be returned.
+     * If not, a new animation will be created.
+     * @param {number} currentValue - The current value of the animation
+     * @param {string} elementId - The id of the element to animate
+     * @param {string} name - The name of the animation
+     * @returns {Animation} The animation
+     */
+    private createSizeAnimation;
+}

package/dist/types/renderers/canvasrenderer/CanvasRenderer.d.ts

@@ -0,0 +1,92 @@
+import type { NvlState } from '../../modules/state';
+import type { Node } from '../../types/graph-element';
+import type { Point } from '../../utils/geometry';
+import type { HitTargetNode, HitTargetRelationship } from '../../utils/hittest';
+import ArrowBundler from './arrows/ArrowBundler';
+export default class CanvasRenderer {
+    arrowBundler: ArrowBundler;
+    private activeNodes;
+    private canvas;
+    private context;
+    private state;
+    private stateDisposers;
+    private relationshipThreshold;
+    private animationHandler;
+    private imageCache;
+    private needsRun;
+    private nodeVersion;
+    private relVersion;
+    private waypointVersion;
+    /**
+     * Creates a new CanvasRenderer.
+     * @param canvas {HTMLCanvasElement} - The canvas to render on.
+     * @param context {CanvasRenderingContext2D} - The canvas context.
+     * @param state {NvlState} - The state.
+     * @param options {{ relationshipThreshold: number }} - The visualization options.
+     */
+    constructor(canvas: HTMLCanvasElement, context: CanvasRenderingContext2D | null, state: NvlState, { relationshipThreshold }?: {
+        relationshipThreshold?: number;
+    });
+    /**
+     * Checks if the renderer needs to run.
+     * @returns {boolean} - Whether the renderer needs to run
+     */
+    needsToRun(): boolean;
+    /**
+     * Processes the updates in nodes and relationships.
+     */
+    processUpdates(): void;
+    /**
+     * Draws the nodes and relationships to their positions on the canvas.
+     * @param positionArray {Node[]} - The array of nodes to draw
+     * @param options {any} - The options for the render
+     */
+    render(positionArray: Node[], options?: {
+        canvas?: HTMLCanvasElement;
+        context?: CanvasRenderingContext2D;
+        backgroundColor?: string;
+        ignoreAnimations?: boolean;
+        showCaptions?: boolean;
+    }): void;
+    private getRelationshipsToRender;
+    private getNodesToRender;
+    private renderNodes;
+    private renderRelationships;
+    /**
+     * Returns the nodes at the pointer position
+     * @param {Point} pointer - the position of the pointer
+     * @returns {HitTargetNode[]} - the nodes at the pointer position
+     * @todo Sort nodes by distance descending
+     */
+    getNodesAt(pointer: Point, hitNodeMarginWidth?: number): HitTargetNode[];
+    /**
+     * Returns the relationships at the pointer position
+     * @param {Point} pointer - the position of the pointer
+     * @returns {HitTargetRelationship[]} - the relationships at the pointer position
+     * @todo: sort relationships by distance descending
+     */
+    getRelsAt(pointer: Point): HitTargetRelationship[];
+    destroy(): void;
+    /**
+     * Checks if the bounding box is outside of the screen.
+     * @param boundingBox - The bounding box to check
+     * @param clientWidth - The client width of the canvas
+     * @param clientHeight - The client height of the canvas
+     * @returns Whether the bounding box is off screen
+     * @note This check doesn't catch all items that are off screen but its simple and removes many of them
+     */
+    private isBoundingBoxOffScreen;
+    /**
+     * Handles the channel's additions, removals and updates and adds or removes the id from the active nodes.
+     * @param channel {Channel<Node>} - The channel to process
+     * @param fullData {DataSet<Node>} - The full data
+     * @param processUpdates {boolean} - Whether to process channel updates as well
+     */
+    private handleChannelUpdate;
+    /**
+     * Handles zoom and pan on the canvas.
+     * @param context {CanvasRenderingContext2D} - The canvas context
+     * @param canvas {HTMLCanvasElement} - The canvas
+     */
+    private zoomAndPan;
+}

package/dist/types/renderers/canvasrenderer/ImageCache.d.ts

@@ -0,0 +1,11 @@
+import type { Cache, CacheInfo, CacheItem } from './types';
+declare class ImageCache {
+    cache: Cache;
+    constructor();
+    getOrCreateEntry(src: string): CacheItem;
+    invertCanvas(ctx: CanvasRenderingContext2D): void;
+    loadImage(src: string): CacheInfo;
+    drawIfNeeded(info: CacheInfo, inverted: boolean): void;
+    getImage(src: string, inverted?: boolean): HTMLCanvasElement;
+}
+export default ImageCache;

package/dist/types/renderers/canvasrenderer/arrows/ArrowBundle.d.ts

@@ -0,0 +1,79 @@
+import type { Relationship } from '../../../types/graph-element';
+import type { Point } from '../../../utils/geometry';
+import type { WaypointPath } from '../types';
+export interface LabelGeometry {
+    position: Point;
+    rotation: number;
+    width: number;
+    height: number;
+}
+/**
+ * Class representing a bundle of arrows
+ */
+export default class ArrowBundle {
+    key: string;
+    rels: {
+        rel: Relationship;
+    }[];
+    waypointPath: WaypointPath;
+    readonly selfReferring: boolean;
+    fromId: string;
+    toId: string;
+    angles: number[];
+    labelInfo: Record<string, LabelGeometry>;
+    /**
+     * @param {string} key - The key of the arrow bundle
+     * @param {string} fromId - The source node of the arrow bundle
+     * @param {string} toId - The target node of the arrow bundle
+     */
+    constructor(key: string, fromId: string, toId: string);
+    /**
+     * Insert a new arrow to the bundle
+     * @param {Relationship} rel - The relationship to insert
+     */
+    insert(rel: Relationship): void;
+    setLabelInfo(relId: string, labelInfo: LabelGeometry): void;
+    /**
+     * Remove an arrow from the bundle
+     * @param {Relationship} rel - The arrow to remove
+     */
+    remove({ id }: Relationship): void;
+    /**
+     * Get the size of the arrow bundle
+     * @returns {number} The size of the arrow bundle
+     */
+    size(): number;
+    /**
+     * Get the maximum font size of the arrows in the bundle
+     * @returns {number} The maximum font size of the arrows in the bundle
+     */
+    maxFontSize(): number;
+    /**
+     * Check if relationship is in opposite direction to the bundle.
+     * @param {Relationship} rel - The relationship to check
+     * @returns {boolean} True if the relationship is in opposite direction to the bundle
+     */
+    relIsOppositeDirection({ from, to }: Relationship): boolean;
+    /**
+     * Get the index of a given arrow in the bundle
+     * @param {Relationship} rel - The arrow to look for
+     * @returns {number} The index of the arrow in the bundle, or -1 if not found
+     */
+    indexOf({ id }: Relationship): number;
+    /**
+     * Get the arrow at a given index in the bundle
+     * @param {number} index - The index of the arrow to get
+     * @returns {Relationship | null} The arrow at the given index
+     */
+    getRel(index: number): Relationship | null;
+    /**
+     * Set the waypoints for the arrow bundle
+     * @param {WaypointPath} waypoints - The waypoints for the arrow bundle
+     */
+    setWaypoints(waypoints: WaypointPath): void;
+    /**
+     * Set the angles for the arrow bundle
+     * @param {number[]} angles - The angles for the arrow bundle
+     */
+    setAngles(angles: number[]): void;
+}

package/dist/types/renderers/canvasrenderer/arrows/ArrowBundler.d.ts

@@ -0,0 +1,33 @@
+import type { Node, Relationship } from '../../../types/graph-element';
+import type { WaypointPath } from '../types';
+import ArrowBundle from './ArrowBundle';
+export default class ArrowBundler {
+    bundles: Record<string, ArrowBundle>;
+    nodeToBundles: Record<string, ArrowBundle[]>;
+    constructor(rels: Relationship[], waypoints: Record<string, WaypointPath>);
+    /**
+     * Get the arrow bundle for a given relation
+     * @param {Relationship} rel - The relationship
+     * @returns {ArrowBundle} The arrow bundle
+     */
+    getBundle(rel: Relationship): ArrowBundle;
+    /**
+     * Update the data
+     * @param {Record<string, Relationship>} addedRels - The added relations
+     * @param {Record<string, Relationship>} removedRels - The removed relations
+     * @param {Record<string, WaypointPath>} waypoints - The waypoints
+     */
+    updateData(addedRels: Record<string, Relationship>, removedRels: Record<string, Relationship>, waypoints: Record<string, WaypointPath>): void;
+    /**
+     * Updates the positions of the arrow bundles based on the provided `positionMap`.
+     * @param positionMap A map of node IDs to positions.
+     */
+    updatePositions(positionMap: Record<string, Node>): void;
+    /**
+     * Get a unique ID for a pair of IDs
+     * @param {string} id1 - The first ID
+     * @param {string} id2 - The second ID
+     * @returns {string} A unique ID for the pair of IDs
+     */
+    private generatePairId;
+}