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

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

@@ -1,80 +1,159 @@
-import type { LogLevelDesc } from 'loglevel';
-import type { WaypointPath } from '../../renderers/domrenderer/shared/types';
-import type { Node } from '../../types/graph-element';
-import type { ExternalCallbacks } from '../ExternalCallbackHandler';
-import type { NodeDataSet, RelationshipDataSet } from '../dataset';
+import { WaypointPath } from "../../renderers/domrenderer/shared/types.js";
+import { Node } from "../../types/graph-element.js";
+import { ExternalCallbacks } from "../ExternalCallbackHandler.js";
+import { NodeDataSet, RelationshipDataSet } from "../dataset.js";
+import { LogLevelDesc } from "loglevel";
 type RingStyle = {
-    width?: number;
-    widthFactor?: number;
-    color: string;
+  width?: number;
+  widthFactor?: number;
+  color: string;
 };
 export type ShadowStyle = {
-    width: number;
-    opacity: number;
-    color: string;
+  width: number;
+  opacity: number;
+  color: string;
 };
 export type BorderStyle = {
-    rings?: RingStyle[];
-    shadow?: ShadowStyle;
+  rings?: RingStyle[];
+  shadow?: ShadowStyle;
 };
 /**
  * @internal
  * @hidden
  */
 export type BorderStyles = {
-    selected: BorderStyle;
-    default: BorderStyle;
+  selected: BorderStyle;
+  default: BorderStyle;
 };
 /**
  * @internal
  * @hidden
  */
 export type DisabledItemStyles = {
-    color: string;
-    fontColor: string;
+  color: string;
+  fontColor: string;
 };
+/**
+ * Identifier returned by {@link ClusterByFn} to group nodes into physical clusters.
+ * Nodes sharing the same string or number are clustered together.
+ */
+export type ClusterId = string | number;
+/**
+ * A physical cluster produced by {@link ClusteringOptions.clusterBy}.
+ * Not a graph element — used for hit-testing and interaction callbacks.
+ */
+export type Cluster = {
+  /** Semantic cluster id returned by {@link ClusterByFn}. */
+  id: ClusterId;
+  /** Real member node ids belonging to this cluster (at least two). */
+  nodeIds: string[];
+};
+/**
+ * Function that maps a node id to a {@link ClusterId} for force-directed clustering.
+ * Returns `undefined` for nodes that should remain independent.
+ */
+export type ClusterByFn = (nodeId: string) => ClusterId | undefined;
+/**
+ * Options that control physical clustering and cluster decorations for the force-directed layout.
+ */
+export interface ClusteringOptions {
+  /**
+   * Optional function to group nodes into physical clusters based on a custom identifier.
+   * Nodes returning the same string or number will be grouped together in the layout.
+   * Nodes returning undefined will be treated as independent.
+   *
+   * @remarks Ensure this function has a stable reference to avoid evaluation on every render.
+   */
+  clusterBy?: ClusterByFn;
+  /**
+   * Draws a convex-hull outline around each cluster.
+   *
+   * @remarks Outline color is the same as the nodes in the cluster.
+   * If the nodes in the cluster have different colors, the outline uses
+   * `NvlOptions.styling.overlayLineColor`.
+   * @defaultValue false
+   */
+  drawOutline?: boolean;
+  /**
+   * Fills a soft glowing halo around each cluster.
+   *
+   * @remarks Halo color is the same as the nodes in the cluster.
+   * If the nodes in the cluster have different colors, the halo won't be shown.
+   * @defaultValue false
+   */
+  drawHalo?: boolean;
+  /**
+   * Spring force multiplier for relationships that cross a {@link ClusteringOptions.clusterBy}
+   * cluster boundary.
+   * Capped between `0` and `1`.
+   * `0` disables cross-cluster spring pull. `1` is full strength. Intra-cluster edges are always
+   * full strength. Only applies when {@link ClusteringOptions.clusterBy} is set.
+   * @defaultValue 0
+   * @experimental
+   * @remarks Can cause unstable layouts when set to close to `1` in highly connected graphs.
+   */
+  crossClusterRelationshipMultiplier?: number;
+}
 /**
  * The options for the force directed layout
  */
 export interface ForceDirectedOptions {
-    /**
-     * Enables a workaround for Intel GPU compatibility issues in WebGL shader compilation.
-     * When enabled, this flag modifies how physics simulation shaders are compiled to avoid
-     * rendering problems on Intel graphics hardware.
-     *
-     * @remarks Requires a restart of NVL as shaders need to be recompiled.
-     *
-     * @deprecated This option will be removed in a future release, where WebGL will be upgraded to WebGL2,
-     * which resolves the compatibility issues with Intel GPUs.
-     */
-    intelWorkaround?: boolean;
-    /**
-     * @deprecated This option will be removed in a future release. For small datasets, use the d3Force layout instead.
-     * Whether to enable automatic switching to CoseBilkent layout for small graphs.
-     * When enabled, small graphs will automatically use the CoseBilkent layout algorithm
-     * which can provide better initial positioning for smaller datasets.
-     * @defaultValue true
-     */
-    enableCytoscape?: boolean;
+  /**
+   * How initial node positions are seeded before the physics simulation runs.
+   * @defaultValue 'box'
+   */
+  seedingMethod?: 'box' | 'circle';
+  /**
+   * Physical clustering and cluster decoration options.
+   */
+  clustering?: ClusteringOptions;
 }
+/**
+ * Returns the clustering options from force-directed layout options, if present.
+ * @param layoutOptions - The layout options to read from.
+ * @returns The clustering options, or undefined when absent / not force-directed.
+ */
+export declare const getClusteringOptions: (layoutOptions?: LayoutOptions) => ClusteringOptions | undefined;
+/**
+ * Whether {@link ClusteringOptions.drawOutline} is enabled on the given layout options.
+ * @param layoutOptions - The layout options to check.
+ * @returns Whether {@link ClusteringOptions.drawOutline} is enabled on the given layout options.
+ */
+export declare const isDrawClusterOutlineEnabled: (layoutOptions?: LayoutOptions) => boolean;
+/**
+ * Whether {@link ClusteringOptions.drawHalo} is enabled on the given layout options.
+ * @param layoutOptions - The layout options to check.
+ * @returns Whether {@link ClusteringOptions.drawHalo} is enabled on the given layout options.
+ */
+export declare const isDrawClusterHaloEnabled: (layoutOptions?: LayoutOptions) => boolean;
 /**
  * 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 direction in which the layout should be oriented */
+  direction?: 'up' | 'down' | 'left' | 'right';
+  /** The packing method to be used */
+  packing?: 'bin' | 'stack';
+  /**
+   * Optional function to group nodes into semantic clusters based on a custom identifier.
+   * Nodes returning the same string or number will be grouped together in the layout via
+   * dagre compound subgraphs. Nodes returning undefined will be treated as independent.
+   *
+   * @remarks Ensure this function has a stable reference to avoid evaluation on every render.
+   *
+   * @experimental
+   */
+  clusterBy?: ClusterByFn;
 }
 export declare const isHierarchicalLayoutOptions: (options: LayoutOptions) => options is HierarchicalOptions;
 /**
  * The options for the circular layout.
  */
 export interface CircularOptions {
-    /**
-     * Function which should return the sorted nodes.
-     */
-    sortFunction?: (nodes: Node[]) => Node[];
+  /**
+   * Function which should return the sorted nodes.
+   */
+  sortFunction?: (nodes: Node[]) => Node[];
 }
 /**
  * NVL's main force directed layout.
@@ -102,11 +181,11 @@ export declare const d3ForceLayoutType = "d3Force";
  */
 export declare const CircularLayoutType = "circular";
 /**
- * A WebGL renderer that uses the GPU for rendering.
+ * A WebGL2 renderer that uses the GPU for rendering.
  *
  * @remarks
  * This renderer has better performance than the canvas renderer,
- * but does not support captions and arrowheads.
+ * but does not support captions.
  */
 export declare const WebGLRendererType = "webgl";
 /**
@@ -114,7 +193,7 @@ export declare const WebGLRendererType = "webgl";
  *
  * @remarks
  * This renderer has lower performance than the WebGL renderer,
- * but supports captions and arrowheads.
+ * but supports captions.
  */
 export declare const CanvasRendererType = "canvas";
 /**
@@ -139,196 +218,227 @@ export type LayoutOptions = ForceDirectedOptions | HierarchicalOptions | Circula
 export type Renderer = typeof WebGLRendererType | typeof CanvasRendererType | typeof SvgRendererType;
 /** Configurations for a NVL instance */
 export interface NvlOptions {
+  /**
+   * Id for uniquely identifying the instance of Nvl
+   */
+  instanceId?: string;
+  /** The graph layout algorithm to be used */
+  layout?: Layout;
+  /**
+   * The minimum zoom level allowed
+   * @defaultValue 0.075
+   */
+  minZoom?: number;
+  /**
+   * The maximum zoom level allowed
+   * @defaultValue 10
+   */
+  maxZoom?: number;
+  /**
+   * Whether or not to dynamically allow decreasing minimum zoom value
+   * if current graph does not fit on screen at minimum zoom.
+   * When set to `true`, zoom and fit operations will allow zooming out
+   * further than {@link NvlOptions.minZoom minZoom} if the graph does not fit on screen.
+   * {@link NvlOptions.minZoom minZoom} is lowered to the new zoom level, so later zoom operations can go that low too.
+   * 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.
+   * @defaultValue true
+   */
+  allowDynamicMinZoom?: boolean;
+  /**
+   * The DOM container in which to render the minimap.
+   *
+   * @remarks When using a React ref, make sure the attached element is rendered before the NVL instance is created.
+   * Otherwise, the minimap will not be displayed.
+   */
+  minimapContainer?: HTMLElement | null;
+  /** 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;
+  /**
+   * What rendering method to use for the visualization.
+   * WebGL renderer uses the GPU and has better performance.
+   * Captions are only displayed when using the canvas or svg renderer.
+   * @defaultValue 'canvas'
+   */
+  renderer?: Renderer;
+  /**
+   * @internal
+   * @hidden
+   * Whether or not to disable WebGL completely.
+   */
+  disableWebGL?: boolean;
+  /**
+   * @internal
+   * @hidden
+   * Specify the log level.
+   */
+  logging?: {
+    level: LogLevelDesc;
+  };
+  /**
+   * @internal
+   * @hidden
+   */
+  relationshipThreshold?: number;
+  /** Callbacks for various events in the NVL instance. */
+  callbacks?: ExternalCallbacks;
+  /** Styling options for the NVL instance. */
+  styling?: {
+    /** The default color for nodes. */
+    defaultNodeColor?: string;
+    /** The default color for relationships. */
+    defaultRelationshipColor?: string;
+    /** The color to use for the default border of nodes */
+    nodeDefaultBorderColor?: string;
+    /** The color to use for the selected border of nodes and relationships */
+    selectedBorderColor?: string;
+    /** The color to use for the selected inner border of nodes and relationships */
+    selectedInnerBorderColor?: string;
+    /** The color to use for the drop shadow of selected/hovered nodes and relationships */
+    dropShadowColor?: string;
+    /** The color to use for the disabled nodes and relationships */
+    disabledItemColor?: string;
+    /** The color to use for the labels of the disabled nodes and relationships */
+    disabledItemFontColor?: string;
     /**
-     * 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.
-     * 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.
-     * @defaultValue true
-     */
-    allowDynamicMinZoom?: boolean;
-    /**
-     * The DOM container in which to render the minimap.
-     *
-     * @remarks When using a React ref, make sure the attached element is rendered before the NVL instance is created.
-     * Otherwise, the minimap will not be displayed.
-     */
-    minimapContainer?: HTMLElement | null;
-    /** 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;
-    /**
-     * What renderer to use
-     * @defaultValue 'canvas'
-     * WebGL renderer uses GPU and has better performance.
-     * Captions and arrowheads are only displayed when using the canvas or svg renderer.
-     */
-    renderer?: Renderer;
-    /**
-     * @internal
-     * @hidden
-     * Whether or not to disable WebGL completely.
-     */
-    disableWebGL?: boolean;
-    /**
-     * @internal
-     * @hidden
-     * Specify the log level.
-     */
-    logging?: {
-        level: LogLevelDesc;
-    };
-    /**
-     * @internal
-     * @hidden
-     */
-    relationshipThreshold?: number;
-    /** Callbacks for various events in the NVL instance. */
-    callbacks?: ExternalCallbacks;
-    /** Styling options for the NVL instance. */
-    styling?: {
-        /** The default color for nodes. */
-        defaultNodeColor?: string;
-        /** The default color for relationships. */
-        defaultRelationshipColor?: string;
-        /** The color to use for the default border of nodes */
-        nodeDefaultBorderColor?: string;
-        /** The color to use for the selected border of nodes and relationships */
-        selectedBorderColor?: string;
-        /** The color to use for the selected inner border of nodes and relationships */
-        selectedInnerBorderColor?: string;
-        /** The color to use for the drop shadow of selected/hovered nodes and relationships */
-        dropShadowColor?: string;
-        /** The color to use for the disabled nodes and relationships */
-        disabledItemColor?: string;
-        /** The color to use for the labels of the disabled nodes and relationships */
-        disabledItemFontColor?: string;
-        /**
-         * Stroke color for overlay UI lines (e.g. minimap viewport box).
-         * Use a dark color on light backgrounds and a light color on dark backgrounds.
-         * @defaultValue `#1A1B1D`
-         */
-        overlayLineColor?: string;
-        /**
-         * The color to use for the viewport box in the minimap.
-         * @deprecated Use {@link overlayLineColor}.
-         */
-        minimapViewportBoxColor?: string;
-    };
-    /**
-     * @internal
-     * @hidden
-     * Defines a time limit for how long layout iterations may run
-     */
-    layoutTimeLimit?: number;
-    /**
-     * Disables tracking of library usage
-     * @defaultValue false
-     */
-    disableTelemetry?: boolean;
-    /**
-     * Disables the use of {@link https://developer.mozilla.org/en-US/docs/Web/API/Web_Workers_API/Using_web_workers | web workers} for the layout calculations.
+     * Stroke color for overlay UI lines (e.g. minimap viewport box).
+     * Use a dark color on light backgrounds and a light color on dark backgrounds.
+     * @defaultValue `#1A1B1D`
      */
-    disableWebWorkers?: boolean;
+    overlayLineColor?: string;
     /**
-     * Disables {@link https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA | ARIA} attributes on the graph.
-     * By default, NVL adds ARIA attributes to the graph container to make it more accessible.
-     * Attributes include `role="image"`, `aria-label="Graph visualization"`
-     * and `aria-describedby="nvl-${instanceId}-description"`.
-     * The description element is a live region that will announce changes to the graph.
-     * @defaultValue false
+     * The color to use for the viewport box in the minimap.
+     * @deprecated Use `overlayLineColor`.
      */
-    disableAria?: boolean;
+    minimapViewportBoxColor?: string;
+  };
+  /**
+   * Target minimum presentation fps while layout is active, at the cost of stabilization speed when set higher.
+   * Budgets layout steps only. Actual fps may undershoot when rendering is expensive.
+   *
+   * @defaultValue 3
+   *
+   * @remarks Will be capped between 1 and 120.
+   */
+  minFps?: number;
+  /**
+   * Target maximum presentation fps while layout is active; extra time in the tick goes to layout stabilization.
+   * Budgets layout steps only. Actual fps may undershoot when rendering is expensive.
+   *
+   * @defaultValue 30
+   *
+   * @remarks Will be capped between 1 and 120.
+   */
+  maxFps?: number;
+  /**
+   * Disables tracking of library usage
+   * @defaultValue false
+   */
+  disableTelemetry?: boolean;
+  /**
+   * Disables the use of {@link https://developer.mozilla.org/en-US/docs/Web/API/Web_Workers_API/Using_web_workers | web workers} for the layout calculations.
+   */
+  disableWebWorkers?: boolean;
+  /**
+   * Disables {@link https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA | ARIA} attributes on the graph.
+   * By default, NVL adds ARIA attributes to the graph container to make it more accessible.
+   * Attributes include `role="image"`, `aria-label="Graph visualization"`
+   * and `aria-describedby="nvl-${instanceId}-description"`.
+   * The description element is a live region that will announce changes to the graph.
+   * @defaultValue false
+   */
+  disableAria?: boolean;
 }
 /** 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;
-    /** If true, will not animate the zoom/pan transition. */
-    animated?: boolean;
+  /** 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. The fit never zooms out further than this.
+   * If {@link NvlOptions.allowDynamicMinZoom} is `true`, it can be lower than {@link NvlOptions.minZoom},
+   * which is then lowered to the resulting zoom level.
+   * If it is `false`, this can only raise the {@link NvlOptions.minZoom} limit, not lower it.
+   */
+  minZoom?: number;
+  /**
+   * The maximum zoom value for the fit-to-zoom operation.
+   * This can only lower the {@link NvlOptions.maxZoom} limit, not raise it.
+   */
+  maxZoom?: number;
+  /** If true, will not animate the zoom/pan transition. */
+  animated?: boolean;
 };
 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;
-    renderer: Renderer;
-    disableWebGL: boolean;
-    disableWebWorkers: boolean;
-    disableTelemetry: boolean;
-    fitMovement: number;
-    layout: Layout;
-    layoutOptions: LayoutOptions;
-    maxNodeRadius: number;
-    maxDistance: number;
+  zoom: number;
+  zoomOptions: ZoomOptions;
+  minimapZoom: number;
+  defaultZoomLevel: number;
+  panX: number;
+  panY: number;
+  minimapPanX: number;
+  minimapPanY: number;
+  fitNodeIds: string[];
+  resetZoom: boolean;
+  forceWebGL: boolean;
+  renderer: Renderer;
+  disableWebGL: boolean;
+  disableWebWorkers: boolean;
+  disableTelemetry: boolean;
+  fitMovement: number;
+  layout: Layout;
+  layoutOptions: LayoutOptions;
+  maxNodeRadius: number;
+  maxDistance: number;
+  minZoom: number;
+  maxZoom: number;
+  allowDynamicMinZoom: boolean;
+  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;
+  lowerMinZoom: (zoom: number) => void;
+  /**
+   * The zoom limits for a fit with the given zoom options. A fit target within these limits is not clamped any
+   * further by the zoom actions, once {@link NvlState.lowerMinZoom} has been called with it.
+   */
+  getFitZoomLimits: (zoomOptions: ZoomOptions) => {
     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;
-    disabledItemStyles: DisabledItemStyles;
-    defaultNodeColor: string;
-    defaultRelationshipColor: string;
-    overlayLineColor: string;
+  };
+  updateMinimapZoomToFit: Function;
+  autorun: Function;
+  reaction: Function;
+  nodeBorderStyles: BorderStyles;
+  relationshipBorderStyles: BorderStyles;
+  disabledItemStyles: DisabledItemStyles;
+  defaultNodeColor: string;
+  defaultRelationshipColor: string;
+  overlayLineColor: string;
 }
-export {};
+export {};