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

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

@@ -1,46 +1,46 @@
-import type { StyledCaption } from '../../renderers/domrenderer/shared/types';
-import type { Node, Relationship } from '../../types/graph-element';
-import type { NvlOptions } from './types';
+import { StyledCaption } from "../../renderers/domrenderer/shared/types.js";
+import { Node, Relationship } from "../../types/graph-element.js";
+import { BorderStyle, NvlOptions, ShadowStyle } from "./types.js";
 /**
  * Converts a {@link Node.caption} string to {@link Node.captions} array format.
  * If both caption and captions are provided, captions takes precedence.
  */
 export declare const processCaptions: (item: Partial<Node | Relationship>) => StyledCaption[];
 export declare const processColorStyles: (styling?: NvlOptions["styling"]) => {
-    nodeBorderStyles: {
-        default: {
-            rings?: {
-                width?: number;
-                widthFactor?: number;
-                color: string;
-            }[];
-            shadow?: import("./types").ShadowStyle;
-        };
-        selected: {
-            rings?: {
-                width?: number;
-                widthFactor?: number;
-                color: string;
-            }[];
-            shadow?: import("./types").ShadowStyle;
-        };
+  nodeBorderStyles: {
+    default: {
+      rings?: {
+        width?: number;
+        widthFactor?: number;
+        color: string;
+      }[];
+      shadow?: ShadowStyle;
     };
-    relationshipBorderStyles: {
-        default: import("./types").BorderStyle;
-        selected: {
-            rings?: {
-                width?: number;
-                widthFactor?: number;
-                color: string;
-            }[];
-            shadow?: import("./types").ShadowStyle;
-        };
+    selected: {
+      rings?: {
+        width?: number;
+        widthFactor?: number;
+        color: string;
+      }[];
+      shadow?: ShadowStyle;
     };
-    disabledItemStyles: {
+  };
+  relationshipBorderStyles: {
+    default: BorderStyle;
+    selected: {
+      rings?: {
+        width?: number;
+        widthFactor?: number;
         color: string;
-        fontColor: string;
+      }[];
+      shadow?: ShadowStyle;
     };
-    defaultNodeColor: string;
-    defaultRelationshipColor: string;
-    overlayLineColor: string;
-};
+  };
+  disabledItemStyles: {
+    color: string;
+    fontColor: string;
+  };
+  defaultNodeColor: string;
+  defaultRelationshipColor: string;
+  overlayLineColor: string;
+};

package/dist/types/renderers/ClusterOverlay.d.ts

@@ -0,0 +1,73 @@
+import { Point } from "../utils/geometry.js";
+import { Node } from "../types/graph-element.js";
+import { NvlState } from "../modules/state/types.js";
+import { CoarsenedGraph } from "../layouts/forcedirectedlayout/clustering/types.js";
+type ClusterPositions = Readonly<Record<string, Point>> | (() => (Node & Point)[]);
+/**
+ * Canvas2D overlay for cluster decorations.
+ */
+export default class ClusterOverlay {
+  private readonly canvas;
+  private readonly context;
+  private readonly state;
+  private readonly stateDisposers;
+  private readonly clusterColors;
+  private clusterColorsDirty;
+  private cachedFirstSubGraphLevel;
+  private cachedIdToPosition;
+  private cachedPositionListVersion;
+  private readonly clusterGeometry;
+  private geometryPositionsVersion;
+  constructor(canvas: HTMLCanvasElement, context: CanvasRenderingContext2D, state: NvlState);
+  /** Clears the overlay. */
+  clear(): void;
+  /**
+   * Draws cluster decorations for a given multi-member first-level sun system and positions.
+   * @param subGraphs - Layout coarsening hierarchy (`subGraphs[1]` = first-level suns).
+   * @param positions - Node id to position map, or a getter for a lagged position list.
+   * @param cacheVersion - PhysLayout positions-cache version.
+   */
+  render(subGraphs: CoarsenedGraph[], positions: ClusterPositions, cacheVersion: number): void;
+  destroy(): void;
+  private resetClusterColorCache;
+  private resetGeometryCache;
+  private syncGeometryCacheVersion;
+  private resetPositionCache;
+  /**
+   * Returns an id to position map. Records are used as-is. Getters are converted once per `cacheVersion`.
+   * @param positions - Node id to position map, or a getter for a lagged position list.
+   * @param cacheVersion - PhysLayout positions-cache version; ignored for maps.
+   * @returns An id to position map.
+   */
+  private resolveIdToPosition;
+  /**
+   * Rebuilds {@link clusterColors} for every multi-member first-level sun.
+   * @param firstSubGraphLevel - `subGraphs[1]` from the current layout coarsening hierarchy.
+   */
+  private rebuildClusterColors;
+  /**
+   * Returns fitted world-space hull for a cluster, reusing the last fit while the
+   * positions cache version is unchanged (e.g. pan/zoom-only frames while layout is stable).
+   * @param sunId - Original id of the sun the hull belongs to.
+   * @param collectMembers - Builds the member disks to fit; only called on a cache miss.
+   * @returns The fitted hull, or null when the cluster cannot be fitted.
+   */
+  private getCachedHull;
+  private fillHalo;
+  private strokeOutline;
+  /**
+   * Traces a closed rounded path along the given points.
+   * @param points - The points to trace the path along.
+   */
+  private traceSmoothClosedPath;
+  private applyZoomAndPan;
+  /**
+   * Returns the shared member color when color is consistent; otherwise null.
+   * @param nodeIds - The IDs of the nodes in the cluster.
+   * @param idToItem - The map of node IDs to items.
+   * @param defaultNodeColor - The default node color.
+   * @returns The shared member color when color is consistent; otherwise null.
+   */
+  private resolveUnanimousClusterColor;
+}
+export {};

package/dist/types/renderers/domrenderer/BaseRenderer.d.ts

@@ -1,75 +1,75 @@
-import type { Channel, DataSet } from '../../modules/dataset';
-import type { NvlState } from '../../modules/state/types';
-import type { Node } from '../../types/graph-element';
-import ImageCache from './shared/ImageCache';
-import ArrowBundler from './shared/arrows/ArrowBundler';
-import type { RelationshipToRender } from './shared/types';
+import { RelationshipToRender } from "./shared/types.js";
+import { Node } from "../../types/graph-element.js";
+import { Channel, DataSet } from "../../modules/dataset.js";
+import { NvlState } from "../../modules/state/types.js";
+import ImageCache from "./shared/ImageCache.js";
+import ArrowBundler from "./shared/arrows/ArrowBundler.js";
 export type RendererOptions = {
-    relationshipThreshold?: number;
+  relationshipThreshold?: number;
 };
 /**
  * Base class for renderers (Canvas and SVG) that provides common functionality
  */
 export default abstract class BaseRenderer {
-    arrowBundler: ArrowBundler;
-    protected state: NvlState;
-    protected relationshipThreshold: number;
-    protected stateDisposers: NvlState['reaction'][];
-    protected needsRun: boolean;
-    protected imageCache: ImageCache;
-    protected nodeVersion: number;
-    protected relVersion: number;
-    protected waypointVersion: number;
-    protected channelId: string;
-    protected activeNodes: Set<string>;
-    constructor(state: NvlState, channelId: string, options?: RendererOptions);
-    /**
-     * Gets relationships to render, sorted by their rendering order
-     * @param showCaptions - Whether to show relationship captions
-     * @param zoom - Current zoom level (optional, used for threshold checking)
-     * @param clientWidth - Width of the rendering area
-     * @param clientHeight - Height of the rendering area
-     * @returns Array of relationships to render, sorted (disabled, normal, selected)
-     */
-    protected getRelationshipsToRender(showCaptions?: boolean, zoom?: number, clientWidth?: number, clientHeight?: number): RelationshipToRender[];
-    /**
-     * Gets nodes to render, sorted by their rendering order
-     * @param positionArray - Array of nodes with positions
-     * @param clientWidth - Width of the rendering area
-     * @param clientHeight - Height of the rendering area
-     * @returns Array of nodes to render, sorted (disabled, normal, selected)
-     */
-    protected getNodesToRender(positionArray: Node[], clientWidth?: number, clientHeight?: number): Node[];
-    /**
-     * Processes updates in nodes and relationships.
-     */
-    processUpdates(): void;
-    /**
-     * Processes node channel updates to track activated nodes.
-     * Adds or removes node IDs from the activeNodes set based on their activated state.
-     * @param channel - The node channel with adds, removes, and updates
-     * @param fullData - The full node dataset
-     */
-    protected processNodeChannelUpdates(channel: Channel<Node>, fullData: DataSet<Node>): void;
-    /**
-     * Checks if a bounding box is off screen
-     * @param boundingBox - The bounding box to check
-     * @param clientWidth - Width of the rendering area
-     * @param clientHeight - Height of the rendering area
-     * @returns Whether the bounding box is off screen
-     */
-    protected isBoundingBoxOffScreen(boundingBox: DOMRect, clientWidth: number, clientHeight: number): boolean;
-    /**
-     * Checks if the renderer needs to run.
-     * @returns Whether the renderer needs to run.
-     */
-    needsToRun(): boolean;
-    /**
-     * Returns a promise that resolves when all images in the cache have finished loading.
-     */
-    waitForImages(): Promise<void>;
-    /**
-     * Cleans up the renderer by disposing state reactions and removing channels.
-     */
-    destroy(): void;
-}
+  arrowBundler: ArrowBundler;
+  protected state: NvlState;
+  protected relationshipThreshold: number;
+  protected stateDisposers: NvlState['reaction'][];
+  protected needsRun: boolean;
+  protected imageCache: ImageCache;
+  protected nodeVersion: number;
+  protected relVersion: number;
+  protected waypointVersion: number;
+  protected channelId: string;
+  protected activeNodes: Set<string>;
+  constructor(state: NvlState, channelId: string, options?: RendererOptions);
+  /**
+   * Gets relationships to render, sorted by their rendering order
+   * @param showCaptions - Whether to show relationship captions
+   * @param zoom - Current zoom level (optional, used for threshold checking)
+   * @param clientWidth - Width of the rendering area
+   * @param clientHeight - Height of the rendering area
+   * @returns Array of relationships to render, sorted (disabled, normal, selected)
+   */
+  protected getRelationshipsToRender(showCaptions?: boolean, zoom?: number, clientWidth?: number, clientHeight?: number): RelationshipToRender[];
+  /**
+   * Gets nodes to render, sorted by their rendering order
+   * @param positionArray - Array of nodes with positions
+   * @param clientWidth - Width of the rendering area
+   * @param clientHeight - Height of the rendering area
+   * @returns Array of nodes to render, sorted (disabled, normal, selected)
+   */
+  protected getNodesToRender(positionArray: Node[], clientWidth?: number, clientHeight?: number): Node[];
+  /**
+   * Processes updates in nodes and relationships.
+   */
+  processUpdates(): void;
+  /**
+   * Processes node channel updates to track activated nodes.
+   * Adds or removes node IDs from the activeNodes set based on their activated state.
+   * @param channel - The node channel with adds, removes, and updates
+   * @param fullData - The full node dataset
+   */
+  protected processNodeChannelUpdates(channel: Channel<Node>, fullData: DataSet<Node>): void;
+  /**
+   * Checks if a bounding box is off screen
+   * @param boundingBox - The bounding box to check
+   * @param clientWidth - Width of the rendering area
+   * @param clientHeight - Height of the rendering area
+   * @returns Whether the bounding box is off screen
+   */
+  protected isBoundingBoxOffScreen(boundingBox: DOMRect, clientWidth: number, clientHeight: number): boolean;
+  /**
+   * Checks if the renderer needs to run.
+   * @returns Whether the renderer needs to run.
+   */
+  needsToRun(): boolean;
+  /**
+   * Returns a promise that resolves when all images in the cache have finished loading.
+   */
+  waitForImages(): Promise<void>;
+  /**
+   * Cleans up the renderer by disposing state reactions and removing channels.
+   */
+  destroy(): void;
+}

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

@@ -2,60 +2,60 @@
  * 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 elementId - The id of the element to animate.
-     * @param startValue - The start value of the animation.
-     */
-    constructor(elementId: string, startValue: number);
-    /**
-     * Sets the duration of the animation.
-     * @param duration - The duration of the animation.
-     * @public
-     */
-    setDuration(duration: number): void;
-    /**
-     * Returns the status of the animation
-     * @returns The status of the animation.
-     * @public
-     */
-    getStatus(): number;
-    /**
-     * Advances the animation to the next frame
-     * @returns True if there is a next animation, false otherwise.
-     * @public
-     */
-    advance(): boolean;
-    /**
-     * Sets the end value of the animation
-     * @param targetValue - The end value of the animation.
-     * @public
-     */
-    setEndValue(targetValue: number): void;
-    /**
-     * Sets the end time of the animation
-     * @param newEndTime - The end time of the animation.
-     * @private
-     */
-    private setEndTime;
-}
+  /** 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 elementId - The id of the element to animate.
+   * @param startValue - The start value of the animation.
+   */
+  constructor(elementId: string, startValue: number);
+  /**
+   * Sets the duration of the animation.
+   * @param duration - The duration of the animation.
+   * @public
+   */
+  setDuration(duration: number): void;
+  /**
+   * Returns the status of the animation
+   * @returns The status of the animation.
+   * @public
+   */
+  getStatus(): number;
+  /**
+   * Advances the animation to the next frame
+   * @returns True if there is a next animation, false otherwise.
+   * @public
+   */
+  advance(): boolean;
+  /**
+   * Sets the end value of the animation
+   * @param targetValue - The end value of the animation.
+   * @public
+   */
+  setEndValue(targetValue: number): void;
+  /**
+   * Sets the end time of the animation
+   * @param newEndTime - The end time of the animation.
+   * @private
+   */
+  private setEndTime;
+}

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

@@ -1,71 +1,71 @@
-import { Animation } from './Animation';
+import { Animation } from "./Animation.js";
 /**
  * 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 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 shouldIgnore - Whether animations should be ignored.
-     */
-    ignoreAnimations(shouldIgnore: boolean): void;
-    /**
-     * Sets the duration for all animations
-     * @param options - An object containing animation durations for fade and size.
-     */
-    setOptions(options: {
-        fadeDuration: number;
-        sizeDuration: number;
-    }): void;
-    /**
-     * Returns whether any animation is running
-     * @returns */
-    needsToRun(): boolean;
-    /**
-     * Returns the current value of an animation
-     * @param elementId - The id of the element the animation is running on.
-     * @param name - The name of the animation.
-     * @returns 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 currentValue - The current value of the animation.
-     * @param elementId - The id of the element to animate.
-     * @param name - The name of the animation.
-     * @returns 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 currentValue - The current value of the animation.
-     * @param elementId - The id of the element to animate.
-     * @param name - The name of the animation.
-     * @returns The animation.
-     */
-    private createSizeAnimation;
-}
+  /** 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 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 shouldIgnore - Whether animations should be ignored.
+   */
+  ignoreAnimations(shouldIgnore: boolean): void;
+  /**
+   * Sets the duration for all animations
+   * @param options - An object containing animation durations for fade and size.
+   */
+  setOptions(options: {
+    fadeDuration: number;
+    sizeDuration: number;
+  }): void;
+  /**
+   * Returns whether any animation is running
+   * @returns */
+  needsToRun(): boolean;
+  /**
+   * Returns the current value of an animation
+   * @param elementId - The id of the element the animation is running on.
+   * @param name - The name of the animation.
+   * @returns 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 currentValue - The current value of the animation.
+   * @param elementId - The id of the element to animate.
+   * @param name - The name of the animation.
+   * @returns 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 currentValue - The current value of the animation.
+   * @param elementId - The id of the element to animate.
+   * @param name - The name of the animation.
+   * @returns The animation.
+   */
+  private createSizeAnimation;
+}