@neo4j-nvl/base 1.2.2 → 2.0.0-1e695738

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

@@ -1,11 +1,14 @@
-import { type Node, type PartialNode, type PartialRelationship, type Relationship } from '../types/graph-element';
-import '../types/nvl-window-functions';
-import type { Point } from '../utils/geometry';
-import type { ExternalCallbacks } from './ExternalCallbackHandler';
-import type { Layout, LayoutOptions, NvlOptions, NvlState, ZoomOptions } from './state/types';
+import { Point } from "../utils/geometry.js";
+import { Node, NodeWithClientPosition, PartialNode, PartialRelationship, Relationship } from "../types/graph-element.js";
+import { ExternalCallbacks } from "./ExternalCallbackHandler.js";
+import { Layout, LayoutOptions, NvlOptions, NvlState, ZoomOptions } from "./state/types.js";
+import { ClusterHitRegion } from "../utils/clusterHitRegions.js";
+import { HitTargetNode, HitTargetRelationship } from "../utils/hitTest.js";
+import "../index.js";
+import "../types/nvl-window-functions.js";
 type SaveToFileOptions = {
-    filename?: string;
-    backgroundColor?: string;
+  filename?: string;
+  backgroundColor?: string;
 };
 export declare const EVENT_ERROR = "onError";
 export declare const EVENT_ZOOM_TRANSITION_DONE = "onZoomTransitionDone";
@@ -14,126 +17,206 @@ export declare const EVENT_LAYOUT_STEP = "onLayoutStep";
 export declare const EVENT_LAYOUT_COMPUTING = "onLayoutComputing";
 export declare const EVENT_WEBGL_CONTEXT_LOST = "onWebGLContextLost";
 export default class NvlController {
-    private destroyed;
-    private readonly state;
-    private readonly callbacks;
-    private readonly instanceId;
-    private readonly glController;
-    private readonly webGLContext;
-    private readonly webGLMinimapContext;
-    private readonly htmlOverlay;
-    private hasResized;
-    private readonly hierarchicalLayout;
-    private readonly gridLayout;
-    private readonly freeLayout;
-    private readonly d3ForceLayout;
-    private readonly circularLayout;
-    private readonly forceLayout;
-    private readonly canvasRenderer;
-    private readonly svgRenderer;
-    private readonly glCanvas;
-    private canvasRect;
-    private readonly glMinimapCanvas;
-    private readonly c2dCanvas;
-    private readonly svg;
-    private isInRenderSwitchAnimation;
-    private previousRenderer;
-    private justSwitchedLayout;
-    private layoutUpdating;
-    private layoutComputing;
-    private isRenderingDisabled;
-    private readonly setRenderSwitchAnimation;
-    private readonly stateDisposers;
-    private readonly zoomTransitionHandler;
-    private currentLayout;
-    private readonly layoutTimeLimit;
-    private pixelRatio;
-    private readonly removeResizeListener;
-    private readonly removeMinimapResizeListener;
-    private pendingZoom;
-    private pendingPan;
-    private pendingViewportOverride;
-    private layoutRunner;
-    private animationRequestId;
-    private layoutDoneCallback;
-    private layoutComputingCallback;
-    private currentLayoutType;
-    private descriptionElement;
-    constructor(state: NvlState, frame: HTMLElement, options: NvlOptions);
-    private onWebGLContextLost;
-    private updateMinimapZoom;
-    private startMainLoop;
-    updateHtmlOverlay(): void;
-    dumpNodes(): Node[];
-    dumpRelationships(): Relationship[];
-    /**
-     * Map a relative Canvas space to the DOM position
-     * @param canvasX - X position in the canvas space.
-     * @param canvasY - Y position position in the canvas space.
-     */
-    mapCanvasSpaceToRelativePosition(canvasX: number, canvasY: number): {
-        x: number;
-        y: number;
-    };
-    /**
-     * Map a relative DOM position to the Canvas space
-     * @param clientX - Relative X position from the top left [0..rect.width].
-     * @param clientY - Relative Y position from the top left [0..rect.height].
-     */
-    mapRelativePositionToCanvasSpace(clientX: number, clientY: number): {
-        x: number;
-        y: number;
-    };
-    getNodePositions(): (Node & Point)[];
-    setNodePositions(data: Node[], updateLayout?: boolean): void;
-    isLayoutMoving(): boolean;
-    getNodesOnScreen(): {
-        nodes: Node[];
-        rels: Relationship[];
-    };
-    registerDoneCallback(cb: NvlController['layoutDoneCallback']): void;
-    registerComputingCallback(cb: NvlController['layoutComputingCallback']): void;
-    getPosition(nodeId: string): Node;
-    getScale(): number;
-    getPan(): {
-        x: number;
-        y: number;
-    };
-    setZoomLevel(_newLevel: number): void;
-    setPanCoordinates(panX: number, panY: number): void;
-    setZoomAndPan(zoom: number, panX: number, panY: number): void;
-    fit(nodeIds: string[], zoomOptions?: ZoomOptions): void;
-    resetZoom(): void;
-    setRenderer(renderer: string): void;
-    on(name: keyof ExternalCallbacks, callback: (args: unknown) => void): void;
-    isDestroyed(): boolean;
-    destroy(): void;
-    callIfRegistered(...args: any[]): void;
-    getCanvasRelsAt(point: Point): import("..").HitTargetRelationship[];
-    getCanvasNodesAt(point: Point, hitNodeMarginWidth?: number): import("..").HitTargetNode[];
-    private getLayout;
-    setLayout(layoutType: Layout): void;
-    setLayoutOptions(options: LayoutOptions): void;
-    private getDataUrlForCanvas;
-    private initiateFileDownload;
-    private updateLayoutAndPositions;
-    saveToFile(options: SaveToFileOptions): void;
-    private createSvgString;
-    saveToSvg(options?: SaveToFileOptions): Promise<void>;
-    getImageDataURL(options: SaveToFileOptions): string;
-    getSvgDataUrl(options?: SaveToFileOptions): Promise<string>;
-    private prepareLargeFileForDownload;
-    private createCanvasAndRenderImage;
-    saveFullGraphToLargeFile(options: SaveToFileOptions): Promise<void>;
-    addAndUpdateElementsInGraph(nodes?: Node[] | PartialNode[], relationships?: Relationship[] | PartialRelationship[]): void;
-    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;
-    private validateNodes;
-    private validateRelationships;
+  private destroyed;
+  private readonly state;
+  private readonly callbacks;
+  private readonly instanceId;
+  private readonly glController;
+  private readonly webGLContext;
+  private readonly webGLMinimapContext;
+  private readonly htmlOverlay;
+  private hasResized;
+  private readonly hierarchicalLayout;
+  private readonly gridLayout;
+  private readonly freeLayout;
+  private readonly d3ForceLayout;
+  private readonly circularLayout;
+  private readonly forceLayout;
+  private readonly canvasRenderer;
+  private readonly svgRenderer;
+  private clusterOverlay;
+  private readonly glCanvas;
+  private canvasRect;
+  private readonly glMinimapCanvas;
+  private readonly c2dCanvas;
+  private clusterOverlayCanvas;
+  private readonly canvasParent;
+  private readonly svg;
+  private isInRenderSwitchAnimation;
+  private previousRenderer;
+  private justSwitchedLayout;
+  private layoutUpdating;
+  private layoutComputing;
+  private isRenderingDisabled;
+  private readonly setRenderSwitchAnimation;
+  private readonly stateDisposers;
+  private readonly zoomTransitionHandler;
+  private currentLayout;
+  private lastTimestamp;
+  private accumulator;
+  private readonly layoutTimeLimit;
+  private readonly smoothFrameBudgetMs;
+  private pixelRatio;
+  private readonly resizeObserver;
+  private readonly minimapResizeObserver;
+  private pendingZoom;
+  private pendingPan;
+  private pendingViewportOverride;
+  private animationRequestId;
+  private layoutDoneCallback;
+  private layoutComputingCallback;
+  private currentLayoutType;
+  private descriptionElement;
+  /** True when a minimap container was provided at construction. */
+  private readonly hasMinimap;
+  private lastMinimapPositions;
+  private lastMinimapCacheVersion;
+  constructor(state: NvlState, frame: HTMLElement, options: NvlOptions);
+  private onWebGLContextLost;
+  private fpsToFrameBudgetMs;
+  private getLayoutNeedsToUpdate;
+  private isWithinBudget;
+  /**
+   * Add elapsed frame time to the layout-step accumulator, capped at `layoutTimeLimit`.
+   * Prevents a slow frame (e.g. blocked GPU readback) from inflating catch-up debt and
+   * scheduling ever more work in a feedback loop; the layout falls behind gracefully instead.
+   */
+  private accumulateLayoutElapsedTime;
+  /**
+   * Whether the GPU force-directed layout is active.
+   * @returns `true` when PhysLayout is the current layout.
+   */
+  private usesGpuSimulation;
+  /**
+   * Whether the GPU-texture fast path can be taken this frame.
+   * Requires the WebGL renderer, GPU layout active, and no CPU-position consumers
+   * (layout-step callback, HTML overlays). A provided minimap no longer blocks this path;
+   * the minimap and cluster overlay are updated from the lagged async position cache instead.
+   * @returns `true` when rendering directly from the GPU position texture is safe.
+   */
+  private canRenderFromGpuTexture;
+  /**
+   * Uploads lagged PhysLayout cache positions to the minimap when the cache version changed.
+   * @returns `true` when positions were refreshed this call.
+   */
+  private refreshMinimapFromCacheIfStale;
+  /**
+   * Fits, renders, and caches minimap positions (and PhysLayout cache version when applicable).
+   */
+  private syncMinimap;
+  /** Whether either cluster decoration is enabled in the current layout options. */
+  private hasClusterDecorations;
+  /**
+   * Creates the decoration canvas and its overlay.
+   * @returns The overlay to draw with.
+   */
+  private createClusterOverlay;
+  /**
+   * Resolves the overlay to draw into, allocating it on first use and tearing it down again
+   * while cluster decorations are off.
+   * @returns The overlay to draw with, or null when decorations are disabled.
+   */
+  private ensureClusterOverlay;
+  /** Tears the overlay and its canvas back down once decorations are switched off. */
+  private destroyClusterOverlay;
+  /**
+   * Draws (or clears) cluster decorations on the Canvas2D overlay from explicit positions.
+   * @param positions - CPU node positions for this frame, or null to clear.
+   */
+  private renderClusterOverlay;
+  /**
+   * Draws cluster decorations from PhysLayout's lagged async PBO cache without a sync dump.
+   * @param forceLayout - The PhysLayout instance to render the cluster overlay from.
+   */
+  private renderClusterOverlayFromCache;
+  /** Syncs idToPosition from the GPU layout on demand; no-op for CPU layouts. */
+  syncPositionsFromLayout(): void;
+  /**
+   * Fitted {@link ClusteringOptions.clusterBy} hull regions for the current layout, or [].
+   * @returns Cluster hit regions for picking.
+   */
+  getClusterByHitRegions(): ClusterHitRegion[];
+  private updateMinimapZoom;
+  private startMainLoop;
+  private renderNodeHtmlOverlays;
+  private renderRelationshipHtmlOverlays;
+  updateHtmlOverlay(): void;
+  dumpNodes(): NodeWithClientPosition[];
+  dumpRelationships(): Relationship[];
+  /**
+   * Map a relative Canvas space to the DOM position
+   * @param canvasX - X position in the canvas space.
+   * @param canvasY - Y position position in the canvas space.
+   */
+  mapCanvasSpaceToRelativePosition(canvasX: number, canvasY: number): {
+    x: number;
+    y: number;
+  };
+  /**
+   * Map a relative DOM position to the Canvas space
+   * @param clientX - Relative X position from the top left [0..rect.width].
+   * @param clientY - Relative Y position from the top left [0..rect.height].
+   */
+  mapRelativePositionToCanvasSpace(clientX: number, clientY: number): {
+    x: number;
+    y: number;
+  };
+  getNodePositions(): (Node & Point)[];
+  setNodePositions(data: Node[], updateLayout?: boolean): void;
+  isLayoutMoving(): boolean;
+  getNodesOnScreen(): {
+    nodes: Node[];
+    rels: Relationship[];
+  };
+  registerDoneCallback(cb: NvlController['layoutDoneCallback']): void;
+  registerComputingCallback(cb: NvlController['layoutComputingCallback']): void;
+  getPosition(nodeId: string): Node & Point;
+  getScale(): number;
+  getPan(): {
+    x: number;
+    y: number;
+  };
+  setZoomLevel(_newLevel: number): void;
+  setPanCoordinates(panX: number, panY: number): void;
+  setZoomAndPan(zoom: number, panX: number, panY: number): void;
+  fit(nodeIds: string[], zoomOptions?: ZoomOptions): void;
+  resetZoom(): void;
+  setRenderer(renderer: string): void;
+  on(name: keyof ExternalCallbacks, callback: (args: unknown) => void): void;
+  isDestroyed(): boolean;
+  destroy(): void;
+  callIfRegistered(...args: any[]): void;
+  getCanvasRelsAt(point: Point): HitTargetRelationship[];
+  getCanvasNodesAt(point: Point, hitNodeMarginWidth?: number): HitTargetNode[];
+  private getLayout;
+  setLayout(layoutType: Layout): void;
+  setLayoutOptions(options?: LayoutOptions): void;
+  /**
+   * Syncs positions if needed and redraws (or clears) the cluster overlay from current state.
+   */
+  private refreshClusterOverlay;
+  private getDataUrlForCanvas;
+  private initiateFileDownload;
+  private updateLayoutAndPositions;
+  private getAndUpdatePositions;
+  private getLayoutPositions;
+  saveToFile(options: SaveToFileOptions): void;
+  private createSvgString;
+  saveToSvg(options?: SaveToFileOptions): Promise<void>;
+  getImageDataURL(options: SaveToFileOptions): string;
+  getSvgDataUrl(options?: SaveToFileOptions): Promise<string>;
+  private prepareLargeFileForDownload;
+  private createCanvasAndRenderImage;
+  saveFullGraphToLargeFile(options: SaveToFileOptions): Promise<void>;
+  addAndUpdateElementsInGraph(nodes?: Node[] | PartialNode[], relationships?: Relationship[] | PartialRelationship[]): void;
+  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;
+  private validateNodes;
+  private validateRelationships;
 }
-export {};
+export {};

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

@@ -1,18 +1,18 @@
 export default class Shader {
-    private readonly shaderProgram;
-    private readonly gl;
-    private curTexture;
-    private attributeInfo;
-    private uniformInfo;
-    constructor(gl: WebGLRenderingContext, vsSource: string, fsSource: string, defines?: {});
-    setUniform(name: string, value: any): void;
-    setAttributePointer(name: string, size: number, start: number, stride: number): void;
-    setAttributePointerFloat(name: string, size: number, start: number, stride: number): void;
-    setAttributePointerUShort(name: string | number, size: number, start: number, stride: number): void;
-    setAttributePointerByteNorm(name: string, size: number, start: number, stride: number): void;
-    setAttributePointerByte(name: string, size: number, start: number, stride: number): void;
-    use(): void;
-    remove(): void;
-    private scanAttributes;
-    private scanUniforms;
-}
+  private readonly shaderProgram;
+  private readonly gl;
+  private curTexture;
+  private attributeInfo;
+  private uniformInfo;
+  constructor(gl: WebGL2RenderingContext, vsSource: string, fsSource: string, defines?: {});
+  setUniform(name: string, value: any): void;
+  setAttributePointer(name: string, size: number, start: number, stride: number): void;
+  setAttributePointerFloat(name: string, size: number, start: number, stride: number): void;
+  setAttributePointerUShort(name: string | number, size: number, start: number, stride: number): void;
+  setAttributePointerByteNorm(name: string, size: number, start: number, stride: number): void;
+  setAttributePointerByte(name: string, size: number, start: number, stride: number): void;
+  use(): void;
+  remove(): void;
+  private scanAttributes;
+  private scanUniforms;
+}

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

@@ -1,25 +1,25 @@
-import PIDController from 'node-pid-controller';
-import type { Node } from '../types/graph-element';
-import type { NvlState } from './state/types';
+import { Node } from "../types/graph-element.js";
+import { NvlState } from "./state/types.js";
+import PIDController from "node-pid-controller";
 export default class ZoomTransitionHandler {
-    xCtrl: PIDController;
-    yCtrl: PIDController;
-    zoomCtrl: PIDController;
-    private getNodePositions;
-    private firstUpdate;
-    private readonly state;
-    private readonly canvas;
-    private readonly stateDisposers;
-    constructor({ state, getNodePositions, canvas }: {
-        state: NvlState;
-        getNodePositions: (data: Node[]) => Node[];
-        canvas: HTMLCanvasElement;
-    });
-    needsToRun(): boolean;
-    update(layoutActive: boolean, onTransitionCompleted?: () => void): void;
-    destroy(): void;
-    private recalculateTarget;
-    private allNodesAreVisible;
-    private reset;
-    private fitNodes;
-}
+  xCtrl: PIDController;
+  yCtrl: PIDController;
+  zoomCtrl: PIDController;
+  private getNodePositions;
+  private firstUpdate;
+  private readonly state;
+  private readonly canvas;
+  private readonly stateDisposers;
+  constructor({ state, getNodePositions, canvas }: {
+    state: NvlState;
+    getNodePositions: (data: Node[]) => Node[];
+    canvas: HTMLCanvasElement;
+  });
+  needsToRun(): boolean;
+  update(layoutActive: boolean, onTransitionCompleted?: () => void): void;
+  destroy(): void;
+  private recalculateTarget;
+  private allNodesAreVisible;
+  private reset;
+  private fitNodes;
+}

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

@@ -1,37 +1,39 @@
-import type { Node, Relationship } from '../types/graph-element';
-import type { Point } from '../utils/geometry';
+import { Point } from "../utils/geometry.js";
+import { Node, Relationship } from "../types/graph-element.js";
 /** A graph stored with mobx. */
 export interface DataSet<T> {
-    items: T[];
-    idToItem: Record<string, T>;
-    channels: Record<string, Channel<T>>;
-    idToPosition: Record<string, Node & Point>;
-    idToHtmlOverlay?: Record<string, HTMLElement>;
-    version: number;
-    addChannel: (this: DataSet<T>, channelName: string) => void;
-    removeChannel: (this: DataSet<T>, channelName: string) => void;
-    clearChannel: (this: DataSet<T>, channelName: string) => void;
-    add: (data: T[], result: ActionResult) => void;
-    update: (data: Partial<T>[], result: ActionResult) => void;
-    remove: (ids: string[], result: ActionResult) => void;
-    updatePositions: (data: Node[]) => void;
-    updateHtmlOverlay: (overlay: HTMLElement) => void;
+  items: T[];
+  idToItem: Record<string, T>;
+  channels: Record<string, Channel<T>>;
+  idToPosition: Record<string, Node & Point>;
+  idToHtmlOverlay?: Record<string, HTMLElement>;
+  version: number;
+  maxDimension: number;
+  addChannel: (this: DataSet<T>, channelName: string) => void;
+  removeChannel: (this: DataSet<T>, channelName: string) => void;
+  clearChannel: (this: DataSet<T>, channelName: string) => void;
+  add: (data: T[], result: ActionResult) => void;
+  update: (data: Partial<T>[], result: ActionResult) => void;
+  remove: (ids: string[], result: ActionResult) => void;
+  updatePositions: (data: Node[]) => void;
+  updateHtmlOverlay: (overlay: HTMLElement) => void;
 }
 export type NodeDataSet = DataSet<Node>;
 export type RelationshipDataSet = DataSet<Relationship>;
 export interface ActionResult {
-    added?: boolean;
-    removed?: boolean;
-    updated?: boolean;
+  added?: boolean;
+  removed?: boolean;
+  updated?: boolean;
 }
 export interface Channel<T> {
-    adds: Record<string, T>;
-    updates: Record<string, T>;
-    removes: Record<string, T>;
+  adds: Record<string, T>;
+  updates: Record<string, T>;
+  removes: Record<string, T>;
 }
-export declare const getHtmlProperty: (item: Partial<Node | Relationship>) => HTMLElement | undefined;
+export declare const getHtmlKey: (item: Node | Relationship) => "html" | "captionHtml";
+export declare const getHtmlProperty: (item: Node | Relationship) => HTMLElement | undefined;
 /**
  * Creates an empty dataset in which a graph be stored and updated using mobx actions.
  * @returns A new and empty {@link DataSet}.
  */
-export declare const createDataSet: <T extends Node | Relationship>() => DataSet<T>;
+export declare const createDataSet: <T extends Node | Relationship>() => DataSet<T>;

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

@@ -1,8 +1,8 @@
-import type { LogLevelDesc, Logger } from 'loglevel';
+import { LogLevelDesc, Logger } from "loglevel";
 declare const nvlLog: Logger;
 export declare const setLogLevel: (level: LogLevelDesc) => void;
 export declare const setupLogging: (logger: Logger, logging: {
-    level: LogLevelDesc;
-    logger?: (methodName: string, args: unknown) => void;
+  level: LogLevelDesc;
+  logger?: (methodName: string, args: unknown) => void;
 }) => void;
-export { nvlLog as log };
+export { nvlLog as log };

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

@@ -1,4 +1,4 @@
-import type { BorderStyles, NvlState } from './types';
+import { BorderStyles, NvlState } from "./types.js";
 export declare const NodeBorderStyles: BorderStyles;
 export declare const RelationshipBorderStyles: BorderStyles;
 export declare const DefaultZoomLevel = 0.75;
@@ -6,4 +6,4 @@ export declare const DefaultMaxZoom = 10;
 export declare const DefaultMinZoom = 0.075;
 export declare const DefaultMinimapMaxZoom = 0.2;
 export declare const DefaultMinimapMinZoom = 0;
-export declare const DefaultZoomOptions: NvlState['zoomOptions'];
+export declare const DefaultZoomOptions: NvlState['zoomOptions'];

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

@@ -1,8 +1,8 @@
-import type { NvlOptions, NvlState } from './types';
+import { NvlOptions, NvlState } from "./types.js";
 /**
  * Create a new NVL state
  *
  * @param options - The options for the new state.
  * @returns The state object.
  */
-export declare const createState: (options: NvlOptions) => NvlState;
+export declare const createState: (options: NvlOptions) => NvlState;