@neo4j-nvl/base 1.0.0 → 1.1.0-01fc2de1

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

@@ -0,0 +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';
+export type RendererOptions = {
+    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;
+}

package/dist/types/renderers/{canvasrenderer → domrenderer/canvasrenderer}/CanvasRenderer.d.ts

@@ -1,42 +1,54 @@
-import type { NvlState } from '../../modules/state/types';
-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;
+import type { NvlState } from '../../../modules/state/types';
+import type { Node } from '../../../types/graph-element';
+import type { Point } from '../../../utils/geometry';
+import type { HitTargetNode, HitTargetRelationship } from '../../../utils/hittest';
+import type { RendererOptions } from '../BaseRenderer';
+import BaseRenderer from '../BaseRenderer';
+export default class CanvasRenderer extends BaseRenderer {
     private canvas;
     private context;
-    private state;
-    private stateDisposers;
-    private relationshipThreshold;
     private animationHandler;
-    private imageCache;
-    private needsRun;
-    private nodeVersion;
-    private relVersion;
-    private waypointVersion;
     private ellipsisWidth;
+    private disableArrowShadow;
     /**
      * 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.
+     * @param options {RendererOptions} - The visualization options.
      */
-    constructor(canvas: HTMLCanvasElement, context: CanvasRenderingContext2D | null, state: NvlState, { relationshipThreshold }?: {
-        relationshipThreshold?: number;
-    });
+    constructor(canvas: HTMLCanvasElement, context: CanvasRenderingContext2D | null, state: NvlState, options?: RendererOptions);
     /**
      * Checks if the renderer needs to run.
      * @returns Whether the renderer needs to run.
      */
     needsToRun(): boolean;
     /**
-     * Processes the updates in nodes and relationships.
+     * Override processUpdates to add Canvas-specific shadow handling
      */
     processUpdates(): void;
+    /**
+     * Draws a single node on the canvas with all its visual elements (circle, icons, captions, etc.)
+     * @param ctx - The canvas rendering context
+     * @param node - The node to draw
+     */
+    private drawNode;
+    /**
+     * Helper method to enable shadow on canvas context
+     */
+    private enableShadow;
+    /**
+     * Helper method to disable shadow on canvas context
+     */
+    private disableShadow;
+    /**
+     * Renders a waypoint arrow (relationship between two different nodes)
+     */
+    private renderWaypointArrow;
+    /**
+     * Renders a self-referencing arrow (relationship from node to itself)
+     */
+    private renderSelfArrow;
     /**
      * Draws the nodes and relationships to their positions on the canvas.
      * @param positionArray {Node[]} - The array of nodes to draw
@@ -49,8 +61,6 @@ export default class CanvasRenderer {
         ignoreAnimations?: boolean;
         showCaptions?: boolean;
     }): void;
-    private getRelationshipsToRender;
-    private getNodesToRender;
     private renderNodes;
     private renderRelationships;
     /**
@@ -67,23 +77,6 @@ export default class CanvasRenderer {
      * @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.
-     * @remarks 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

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

@@ -0,0 +1,168 @@
+import type { BorderStyle, DisabledItemStyles } from '../../../modules/state/types';
+import type { Relationship } from '../../../types/graph-element';
+import type { Point } from '../../../utils/geometry';
+import type ArrowBundle from '../shared/arrows/ArrowBundle';
+/**
+ * Calculate label dimensions including font size, font weight, and truncated text.
+ *
+ * @param fullCaption - The complete caption text
+ * @param relWidth - The relationship width (may be undefined)
+ * @param selected - Whether the relationship is selected (affects font weight and width calculation)
+ * @param captionSize - The caption size multiplier (default 1)
+ * @param defaultRelWidth - The default relationship width to use if relWidth is undefined
+ * @param measureWidth - Function to measure text width given a text string
+ * @param maxWidth - The maximum width available for the label in pixels
+ * @returns LabelDimensions with calculated font metrics and label text
+ */
+export declare const calculateLabelDimensions: (fullCaption: string, measureWidth: (text: string) => number, maxWidth: number) => {
+    label: string;
+    width: number;
+};
+/**
+ * Calculate label transform including rotation and flip adjustments.
+ *
+ * @param angle - The base rotation angle in radians
+ * @param fontSize - The font size in pixels (including pixel ratio scaling)
+ * @param flip - Whether to flip the label (applies additional rotation)
+ * @param point - The base point (used to calculate offset in flip case)
+ * @returns object with final position and angle
+ */
+export declare const calculateLabelTransform: (angle: number, fontSize: number, flip: boolean, point: Point) => {
+    finalX: number;
+    finalY: number;
+    finalAngle: number;
+};
+/**
+ * Calculate vertical alignment offset for label based on caption alignment.
+ *
+ * @param captionAlign - The caption alignment: 'top' or 'bottom'
+ * @param fontSize - The font size in pixels (including pixel ratio scaling)
+ * @param lineWidth - The relationship line width in pixels
+ * @param padding - The padding around the label in pixels
+ * @returns The vertical offset in pixels to apply when drawing the label
+ */
+export declare const calculateLabelHeightAlign: (captionAlign: string, fontSize: number, lineWidth: number, padding: number) => number;
+/**
+ * Calculate final label geometry for hit detection.
+ *
+ * @param point - The original point (before transform)
+ * @param angle - The rotation angle in radians
+ * @param maxWidth - The maximum width of the label in pixels
+ * @param fontSize - The font size in pixels (including pixel ratio scaling)
+ * @param heightAlign - The vertical alignment offset in pixels
+ * @param padding - The padding around the label in pixels
+ * @param pixelRatio - The device pixel ratio
+ * @param flip - Whether the label is flipped
+ * @returns object with position, rotation, width, and height for hit detection
+ */
+export declare const calculateLabelGeometry: (point: Point, angle: number, maxWidth: number, fontSize: number, heightAlign: number, padding: number, pixelRatio: number, flip: boolean) => {
+    position: {
+        x: number;
+        y: number;
+    };
+    rotation: number;
+    width: number;
+    height: number;
+};
+/**
+ * Determines the rendering state flags for a relationship.
+ *
+ * @param rel - The relationship to analyze
+ * @param disableArrowShadow - Global flag to disable arrow shadows
+ * @param showLabel - Whether the relationship label is visible
+ * @returns Object containing rendering state flags
+ */
+export declare const determineArrowRenderingState: (rel: Relationship, disableArrowShadow: boolean, showLabel: boolean) => {
+    isSelected: boolean;
+    isDisabled: boolean;
+    showOverlayIcon: boolean;
+    shouldRenderShadow: boolean;
+    shouldShowHoverEffect: boolean;
+};
+/**
+ * Selects relationship colors based on rendering state.
+ *
+ * @param rel - The relationship to get colors for
+ * @param selectedBorderStyle - The selected border style containing ring colors
+ * @param disabledItemStyles - Styling for disabled items
+ * @param defaultColor - Default color to use if none is specified
+ * @returns Object containing colors for different rendering layers
+ */
+export declare const selectArrowColors: (rel: Relationship, selectedBorderStyle: BorderStyle, disabledItemStyles: DisabledItemStyles, defaultColor: string) => {
+    mainColor: string;
+    selectedColor1: string;
+    selectedColor2: string;
+    hoverColor: string;
+};
+/**
+ * Calculates arrowhead adjustment for last segment truncation.
+ *
+ * @param lastSegmentDistance - Distance between the last two points
+ * @param headHeight - Height of the arrowhead
+ * @param headPositionOffset - Base position offset for the arrowhead (HeadChinHeight - headSelectedAdjustment)
+ * @param headSelectedAdjustment - Additional adjustment for selected state
+ * @param headChinHeight - Height of the arrowhead's chin (base)
+ * @param isSelected - Whether the arrow is selected
+ * @returns Object containing adjusted parameters and truncation flag
+ */
+export declare const calculateArrowheadAdjustment: (lastSegmentDistance: number, headHeight: number, headPositionOffset: number, headSelectedAdjustment: number, headChinHeight: number, isSelected: boolean) => {
+    adjustedHeadPositionOffset: number;
+    adjustedHeadSelectedAdjustment: number;
+    shouldTruncateLastSegment: boolean;
+};
+/**
+ * The parameters for drawing an arrowhead.
+ */
+type ArrowHeadParameters = {
+    headPosition: Point;
+    headAngle: number;
+    headHeight: number;
+    headChinHeight: number;
+    headWidth: number;
+};
+/**
+ * Creates an arrowhead shape using a polygon.
+ * @param ctx - The canvas context to draw on.
+ * @param headLineWidth - The width of the arrowhead's outline.
+ * @param color - The color of the arrowhead.
+ * @param arrowHeadParameters - The parameters for the arrowhead.
+ * @param fill - Whether or not to fill the triangle.
+ * @param stroke - Whether or not to stroke the triangle.
+ */
+export declare const drawArrowHead: (ctx: CanvasRenderingContext2D, headLineWidth: number, color: string, arrowHeadParameters: ArrowHeadParameters, fill?: boolean, stroke?: boolean) => void;
+/**
+ * Draws line segments on canvas (straight or curved).
+ *
+ * @param ctx - The canvas rendering context
+ * @param points - The array of points defining the segments
+ * @param width - The line width
+ * @param style - The stroke style (color)
+ * @param drawCurves - Whether to draw smooth curves through points
+ */
+export declare const drawSegments: (ctx: CanvasRenderingContext2D, points: Point[], width: number, style: string, drawCurves: boolean) => void;
+/**
+ * Draws a self-referencing loop on canvas using two quadratic Bézier curves.
+ *
+ * @param ctx - The canvas rendering context
+ * @param fromPoint - The start point of the loop
+ * @param toPoint - The end point of the loop
+ * @param apexPoint - The top point of the loop arc
+ * @param control1Point - Control point for the first curve segment
+ * @param control2Point - Control point for the second curve segment
+ */
+export declare const drawLoop: (ctx: CanvasRenderingContext2D, fromPoint: Point, toPoint: Point, apexPoint: Point, control1Point: Point, control2Point: Point) => void;
+/**
+ * Draws a label for a relationship on canvas.
+ *
+ * @param ctx - The canvas rendering context
+ * @param point - The position to draw the label at
+ * @param angle - The rotation angle for the label
+ * @param maxWidth - The maximum width available for the label
+ * @param rel - The relationship to draw the label for
+ * @param bundle - The arrow bundle containing label info
+ * @param disabledItemStyles - Styles for disabled items
+ * @param fontColor - The font color to use
+ * @param flip - Whether to flip the label orientation (default false)
+ */
+export declare const drawLabel: (ctx: CanvasRenderingContext2D, point: Point, angle: number, maxWidth: number, rel: Relationship, bundle: ArrowBundle, disabledItemStyles: DisabledItemStyles, fontColor: string, flip?: boolean) => void;
+export {};

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

@@ -0,0 +1,109 @@
+import type { BorderStyle, DisabledItemStyles, ShadowStyle } from '../../../modules/state/types';
+import type { Node } from '../../../types/graph-element';
+import type { TextSegment } from '../shared/types';
+import type AnimationHandler from './AnimationHandler';
+/**
+ * Draws borders around a node with a given array of border styles
+ * @param ctx - The canvas context.
+ * @param x - The x coordinate of the node.
+ * @param y - The y coordinate of the node.
+ * @param innerRadius - The inner radius of the node without any border.
+ * @param borderStyles - An array of border styles.
+ * @internal
+ * @hidden
+ */
+export declare const drawCircleBand: (ctx: CanvasRenderingContext2D, x: number, y: number, innerRadius: number, borderStyles: {
+    width: number;
+    color: string;
+}[]) => void;
+/**
+ * Fill a circle band with a gradient from a certain color to transparent
+ * @param ctx - The canvas context.
+ * @param x - The x coordinate of the node.
+ * @param y - The y coordinate of the node.
+ * @param color - The color of the gradient.
+ * @param radius - The inner radius of the node without any border.
+ * @param blur - The blur radius of the gradient.
+ * @param maxOpacity - The maximum opacity of the gradient.
+ */
+export declare const drawGradientCircleBand: (ctx: CanvasRenderingContext2D, x: number, y: number, color: string, radius: number, blur: number, maxOpacity?: number) => void;
+/**
+ * Draw a circle shape with a solid color
+ */
+export declare const drawSolidCircle: (ctx: CanvasRenderingContext2D, x: number, y: number, color: string, size: number) => void;
+/**
+ * Prints the caption for a node
+ */
+export declare const drawNodeCaption: (ctx: CanvasRenderingContext2D, lines: TextSegment[], stylesPerChar: string[][], initialYPos: number, fontSize: number, fontFace: string, lineDistance: number, x: number, y: number, ellipsisWidth: number) => void;
+/**
+ * Calculate pulse animation parameters based on current animation state.
+ * The pulse grows from the node center to 1.88x the node radius, then fades out.
+ * This creates an expanding circle effect.
+ *
+ * @param nodeId - The unique identifier of the node
+ * @param animationHandler - The animation handler managing animation state
+ * @param mainFaceRadius - The radius of the main node circle in pixels
+ * @returns The calculated pulse radius
+ */
+export declare const calculatePulseAnimation: (mainFaceRadius: number) => {
+    pulseRadius: number;
+    pulseVisibility: number;
+};
+/**
+ * Calculate shadow animation parameters based on node state.
+ * Animates shadow width from 0 to target based on selected/hovered state.
+ *
+ * @param nodeId - The unique identifier of the node
+ * @param animationHandler - The animation handler managing animation state
+ * @param selected - Whether the node is selected
+ * @param hovered - Whether the node is hovered
+ * @param shadowStyle - The shadow style configuration
+ * @returns Object with shadowWidth, shadowFade, and shadowColor, or null if no shadow needed
+ */
+export declare const calculateShadowAnimation: (nodeId: string, animationHandler: AnimationHandler, selected: boolean, hovered: boolean, shadowStyle: ShadowStyle) => {
+    shadowWidth: number;
+    shadowColor: string;
+    shadowFade: number;
+};
+/**
+ * Returns an array of styles for the rings of a node.
+ * If the node is selected, it uses the selected ring styles.
+ * Otherwise, it uses the default ring styles.
+ * When no rings are configured, existing ring animations are wound down.
+ *
+ * @param node - The node to get the ring styles for.
+ * @param animationHandler - The animation handler.
+ * @param nodeBorderStyles - The node border styles.
+ * @returns An array of ring styles with computed widths.
+ */
+export type NodeRenderParamsInput = {
+    node: Node;
+    mainFaceRadius: number;
+    disabled: boolean;
+    disabledItemStyles: DisabledItemStyles;
+    selectedBorderStyle: BorderStyle;
+    animationHandler: AnimationHandler;
+    defaultNodeColor: string;
+};
+/**
+ * Calculate all node render parameters at once.
+ * This is the main entry point for preparing node rendering calculations.
+ *
+ * @param input - The input parameters object
+ * @returns object with node render parameters
+ */
+export declare const calculateNodeRenderParams: (input: NodeRenderParamsInput) => {
+    nodeColor: string;
+    fontColor: string;
+    shouldRenderPulse: boolean;
+    pulseAnimation: {
+        pulseColor: string;
+        pulseRadius: number;
+    };
+    shouldRenderShadow: boolean;
+    shadowAnimation: {
+        shadowWidth: number;
+        shadowFade: number;
+        shadowColor: string;
+    };
+};

package/dist/types/renderers/domrenderer/shared/ImageCache.d.ts

@@ -0,0 +1,16 @@
+import type { Cache } from '../shared/types';
+declare class ImageCache {
+    cache: Cache;
+    constructor();
+    getImage(src: string, inverted?: boolean): HTMLCanvasElement;
+    private getOrCreateEntry;
+    private invertCanvas;
+    private loadImage;
+    private drawIfNeeded;
+    /**
+     * Returns a promise that resolves when all images currently in the cache have finished loading.
+     * Useful before export operations to ensure all icons are available.
+     */
+    waitForImages(): Promise<void>;
+}
+export default ImageCache;

package/dist/types/renderers/{canvasrenderer → domrenderer/shared}/arrows/ArrowBundle.d.ts

@@ -1,5 +1,5 @@
-import type { Relationship } from '../../../types/graph-element';
-import type { Point } from '../../../utils/geometry';
+import type { Relationship } from '../../../../types/graph-element';
+import type { Point } from '../../../../utils/geometry';
 import type { WaypointPath } from '../types';
 export interface LabelGeometry {
     position: Point;
@@ -19,12 +19,28 @@ export default class ArrowBundle {
     toId: string;
     angles: number[];
     labelInfo: Record<string, LabelGeometry>;
+    relIndexCache: Map<string, number>;
+    relDirectionCache: Map<string, boolean>;
+    private cachedMaxFontSize;
     /**
      * @param key - The key of the arrow bundle.
      * @param fromId - The source node of the arrow bundle.
      * @param toId - The target node of the arrow bundle.
      */
     constructor(key: string, fromId: string, toId: string);
+    /**
+     * Recalculate and cache the maximum font size
+     */
+    updateMaxFontSize(): void;
+    /**
+     * Updates the relationship direction cache with a given relationship
+     * @param rel - The relationship to update the direction for.
+     */
+    updateRelDirection(rel: Relationship): void;
+    /**
+     * Regenerates index cache for rel ids in bundle
+     */
+    updateIndexCache(): void;
     /**
      * Insert a new arrow to the bundle
      * @param rel - The relationship to insert.
@@ -53,7 +69,7 @@ export default class ArrowBundle {
      * @param rel - The relationship to check.
      * @returns True if the relationship is in opposite direction to the bundle.
      */
-    relIsOppositeDirection({ from, to }: Relationship): boolean;
+    relIsOppositeDirection({ id }: Relationship): boolean;
     /**
      * Get the index of a given arrow in the bundle
      * @param rel - The arrow to look for.
@@ -65,7 +81,7 @@ export default class ArrowBundle {
      * @param index - The index of the arrow to get.
      * @returns The arrow at the given index.
      */
-    getRel(index: number): Relationship | null;
+    getRel(index: number): Relationship;
     /**
      * Set the waypoints for the arrow bundle
      * @param waypoints - The waypoints for the arrow bundle.

package/dist/types/renderers/{canvasrenderer → domrenderer/shared}/arrows/ArrowBundler.d.ts

@@ -1,9 +1,10 @@
-import type { Node, Relationship } from '../../../types/graph-element';
+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[]>;
+    relToBundleKey: Map<string, string>;
     constructor(rels: Relationship[], waypoints: Record<string, WaypointPath>);
     /**
      * Get the arrow bundle for a given relation
@@ -23,6 +24,15 @@ export default class ArrowBundler {
      * @param positionMap A map of node IDs to positions.
      */
     updatePositions(positionMap: Record<string, Node>): void;
+    /**
+     * Remove a bundle reference from the node→bundles index for one node id.
+     */
+    private removeNodeFromMap;
+    /**
+     * Remove a relationship from a bundle.
+     * If the bundle is now empty, remove it from `bundles` and the node index.
+     */
+    private removeRelFromBundle;
     /**
      * Get a unique ID for a pair of IDs
      * @param id1 - The first ID.

package/dist/types/renderers/domrenderer/shared/arrows/ArrowBundler.test.d.ts

@@ -0,0 +1 @@
+export {};