polly-graph 0.2.3 → 0.2.5

package/dist/index.d.ts

@@ -303,6 +303,11 @@ interface SelectionInteractionConfig {
     readonly nodeStyle?: Partial<NodeStyle>;
     readonly linkStyle?: Partial<LinkStyle>;
 }
+interface HighlightInteractionConfig {
+    readonly enabled?: boolean;
+    readonly nodeStyle?: Partial<NodeStyle>;
+    readonly linkStyle?: Partial<LinkStyle>;
+}
 interface DragInteractionConfig {
     readonly enabled?: boolean;
 }
@@ -310,6 +315,7 @@ interface GraphInteractionConfig {
     readonly drag?: DragInteractionConfig;
     readonly hover?: HoverInteractionConfig;
     readonly selection?: SelectionInteractionConfig;
+    readonly highlight?: HighlightInteractionConfig;
 }
 
 type LegendPosition = 'top-left' | 'top-right' | 'bottom-left' | 'bottom-right';
@@ -377,6 +383,7 @@ interface V2Link extends SimulationLinkDatum<V2Node> {
 interface InteractionConfig {
     readonly hover?: HoverInteractionConfig;
     readonly selection?: SelectionInteractionConfig;
+    readonly highlight?: HighlightInteractionConfig;
 }
 interface V2Config {
     container: HTMLElement;
@@ -406,6 +413,11 @@ interface V2Instance {
     zoomIn(factor?: number, center?: [number, number]): void;
     zoomOut(factor?: number, center?: [number, number]): void;
     clearSelection(): void;
+    highlightNode(nodeId: string): void;
+    highlightNodes(nodeIds: string[]): void;
+    unhighlightNode(nodeId: string): void;
+    clearHighlights(): void;
+    getHighlightedNodes(): Set<string>;
     on(event: 'nodeSelect', handler: (node: V2Node, element: HTMLCanvasElement) => void): () => void;
     on(event: 'nodeDeselect', handler: (node: V2Node, element: HTMLCanvasElement) => void): () => void;
     on(event: 'linkSelect', handler: (link: V2Link, element: HTMLCanvasElement) => void): () => void;
@@ -428,6 +440,17 @@ interface V2Instance {
     resetPerformanceMetrics(): void;
 }
 
+interface PhysicsConfig {
+    nodes: V2Node[];
+    links: V2Link[];
+    width: number;
+    height: number;
+    onTick: () => void;
+    onEnd?: () => void;
+    autoFitView?: boolean;
+    cooldownTime?: number;
+}
+
 /**
  * V2 Canvas Graph - Error Handling
  */
@@ -604,29 +627,38 @@ declare class CanvasManager {
  * Manages D3 force simulation lifecycle and behavior
  */
 
-interface PhysicsConfig {
-    nodes: V2Node[];
-    links: V2Link[];
-    width: number;
-    height: number;
-    onTick: () => void;
-    onEnd?: () => void;
-    autoFitView?: boolean;
-    cooldownTime?: number;
-}
 declare class PhysicsManager {
     private simulation?;
     private config?;
     private simulationStartTime?;
     private simulationEndTime?;
-    private cooldownTimer?;
     private hasInitialAutoFitCompleted;
     private timerManager;
+    private isVisibilityListenerAttached;
+    private stateManager;
+    private isWarmingUp;
+    private warmupSteps;
     constructor(timerManager: TimerManager);
     /**
      * Initialize physics simulation
      */
     initialize(config: PhysicsConfig): void;
+    /**
+     * Handle tick with smooth warmup progression
+     */
+    private handleTick;
+    /**
+     * Start smooth warmup process for large graphs
+     */
+    private startSmoothWarmup;
+    /**
+     * Progress warmup over time for smoother initial animation
+     */
+    private progressWarmup;
+    /**
+     * Apply scaled forces during warmup
+     */
+    private applyWarmupForces;
     /**
      * Handle simulation end
      */
@@ -673,20 +705,12 @@ declare class PhysicsManager {
      * Calculate base distance based on graph size and node count
      */
     private calculateBaseDistance;
-    /**
-     * Find node by ID
-     */
-    private findNodeById;
-    /**
-     * Get node radius from style or default
-     */
-    private getNodeRadius;
     /**
      * Get arrow length from link style or default
      */
     private getLinkArrowLength;
     /**
-     * Initialize node positions if not set
+     * Initialize node positions with improved distribution for smoother startup
      */
     initializePositions(): void;
     /**
@@ -715,6 +739,7 @@ declare class PhysicsManager {
      * Resume the simulation
      */
     resume(): void;
+    private handleVisibilityChange;
     /**
      * Destroy physics simulation
      */
@@ -766,6 +791,7 @@ declare class HoverManager {
     private flushShadowCanvas?;
     private hasValidPointerPosition;
     private containerWarningLogged;
+    private boundHandlers;
     /**
      * Initialize hover manager with force-graph pattern
      */
@@ -850,6 +876,10 @@ interface DragConfig {
     physicsManager: PhysicsManager;
     hoverManager: HoverManager;
     onRender: () => void;
+    renderer?: {
+        setDragState(isDragging: boolean): void;
+        setDraggedNode(node: V2Node): void;
+    };
 }
 interface DragState {
     isDragging: boolean;
@@ -859,6 +889,9 @@ declare class DragManager {
     private config?;
     private state;
     private readonly DRAG_CLICK_TOLERANCE_PX;
+    private dragRenderPending;
+    private lastDragRenderTime;
+    private pendingAnimationFrame?;
     /**
      * Initialize drag behavior
      */
@@ -875,6 +908,10 @@ declare class DragManager {
      * Handle drag movement
      */
     private handleDrag;
+    /**
+     * RAF-throttled render during drag (like ZoomManager pattern)
+     */
+    private throttledDragRender;
     /**
      * Handle drag end
      */
@@ -907,6 +944,10 @@ interface ZoomConfig {
     canvas: HTMLCanvasElement;
     canvasManager: CanvasManager;
     onRender: () => void;
+    onZoomEnd?: () => void;
+    renderer?: {
+        setZoomState(isZooming: boolean): void;
+    };
     minZoom?: number;
     maxZoom?: number;
     isOverEntity?: () => boolean;
@@ -914,6 +955,9 @@ interface ZoomConfig {
 declare class ZoomManager {
     private config?;
     private zoomBehavior?;
+    private isZooming;
+    private zoomRenderPending;
+    private isProgrammaticZoom;
     /**
      * Initialize zoom behavior
      */
@@ -927,13 +971,14 @@ declare class ZoomManager {
      */
     private handleZoomStart;
     /**
-     * Handle zoom events
+     * Handle zoom events with RAF throttling for smooth performance
      */
     private handleZoom;
     /**
      * Handle zoom end (when panning ends)
      */
     private handleZoomEnd;
+    isCurrentlyZooming(): boolean;
     /**
      * Get zoom behavior instance
      */
@@ -1015,6 +1060,7 @@ declare class SelectionManager {
     private selectionState;
     private eventHandlers;
     private container?;
+    private boundHandlers;
     /**
      * Initialize selection manager
      */
@@ -1082,161 +1128,263 @@ declare class SelectionManager {
 }
 
 /**
- * V2 Canvas Graph - Renderer (Force-Graph Pattern)
+ * V2 Canvas Graph - State Manager
  *
- * Clean implementation following force-graph's exact architecture
+ * Centralized state management for O(1) lookups across all renderers.
+ * Eliminates duplicate Maps and provides consistent caching patterns.
  */
 
-declare class Renderer {
-    private config?;
-    private canvasState?;
-    private hoverManager?;
-    private selectionManager?;
-    private styleResolver?;
+interface GraphState {
+    nodes: V2Node[];
+    links: V2Link[];
+}
+interface NodeLookupState {
+    isHovered: boolean;
+    isSelected: boolean;
+    isHighlighted: boolean;
+}
+interface LinkLookupState {
+    isHovered: boolean;
+    isSelected: boolean;
+}
+declare class StateManager {
     private nodeMap;
-    private shadowCanvasDirty;
-    private lastShadowRenderTime;
-    private readonly SHADOW_RENDER_THROTTLE;
-    private hasLoggedLargeGraphOptimization;
-    private performanceMetrics;
-    private linkHoverPrecision;
+    private linkMap;
+    private nodeStateCache;
+    private linkStateCache;
+    private linkIdToLinkMap;
+    private highlightedNodes;
     /**
-     * Initialize the renderer
+     * Initialize with graph data
      */
-    initialize(config: {
-        nodes: V2Node[];
-        links: V2Link[];
-        interaction?: InteractionConfig;
-    }, canvasState: CanvasState, hoverManager: HoverManager, selectionManager?: SelectionManager): void;
+    initialize(state: GraphState): void;
     /**
-     * Main render method with performance metrics (Instrumented)
+     * Update with new graph data
      */
-    render(): void;
+    updateState(state: GraphState): void;
     /**
-     * Render with transform (called during zoom/pan) with shadow canvas dirty marking (Step 6 optimization)
+     * Build node map for O(1) node lookups
      */
-    renderWithTransform(): void;
+    private buildNodeMap;
     /**
-     * Render shadow canvas for hit detection with throttling (Step 6 optimization)
+     * Build link maps for O(1) link lookups
      */
-    renderShadowCanvas(): void;
+    private buildLinkMaps;
     /**
-     * Mark shadow canvas as dirty for next render (Step 6 optimization)
+     * Get node by ID (O(1) lookup)
      */
-    markShadowCanvasDirty(): void;
+    getNode(nodeId: string): V2Node | undefined;
     /**
-     * Force shadow canvas render (Step 6 optimization)
+     * Get link by link ID (O(1) lookup)
      */
-    forceShadowCanvasRender(): void;
+    getLink(linkId: string): V2Link | undefined;
     /**
-     * Clear canvas context
+     * Get link by source/target IDs (O(1) lookup)
      */
-    private clearCanvas;
+    getLinkByNodes(sourceId: string, targetId: string): V2Link | undefined;
     /**
-     * Apply transform to canvas context
+     * Get all nodes (returns reference to avoid copying)
      */
-    private applyTransform;
+    getAllNodes(): V2Node[];
     /**
-     * Get unique link ID for tracking (consistent with LinkLabelsRenderer)
+     * Get all links (returns reference to avoid copying)
      */
-    private getLinkId;
+    getAllLinks(): V2Link[];
     /**
-     * Render main canvas nodes
+     * Get node map (for renderers that need direct map access)
      */
-    private renderNodes;
+    getNodeMap(): Map<string, V2Node>;
     /**
-     * Render node labels
+     * Get link ID to link map (for renderers that need direct map access)
      */
-    private renderNodeLabels;
+    getLinkIdToLinkMap(): Map<string, V2Link>;
     /**
-     * Render shadow links with __indexColor (force-graph pattern)
+     * Cache node state for performance (avoid repeated hover/selection checks)
      */
-    private renderShadowLinks;
+    cacheNodeState(nodeId: string, state: NodeLookupState): void;
     /**
-     * Render shadow link labels for hit detection
+     * Get cached node state
      */
-    private renderShadowLinkLabels;
+    getCachedNodeState(nodeId: string): NodeLookupState | undefined;
     /**
-     * Render shadow nodes with __indexColor (force-graph pattern)
+     * Cache link state for performance (avoid repeated hover/selection checks)
      */
-    private renderShadowNodes;
+    cacheLinkState(linkId: string, state: LinkLookupState): void;
     /**
-     * Get currently hovered node ID directly (Critical Performance Fix)
+     * Get cached link state
      */
-    private getCurrentlyHoveredNodeId;
+    getCachedLinkState(linkId: string): LinkLookupState | undefined;
     /**
-     * Get currently selected node ID directly (Critical Performance Fix)
+     * Clear state caches (call when hover/selection state changes)
      */
-    private getCurrentlySelectedNodeId;
+    clearStateCache(): void;
     /**
-     * Get currently hovered link (Critical Performance Fix)
+     * Clear only node state cache
      */
-    private getCurrentlyHoveredLink;
+    clearNodeStateCache(): void;
     /**
-     * Get currently selected link (Critical Performance Fix)
+     * Clear only link state cache
      */
-    private getCurrentlySelectedLink;
+    clearLinkStateCache(): void;
     /**
-     * Log performance metrics for analysis
+     * Generate consistent link ID
      */
-    private logPerformanceMetrics;
+    getLinkId(link: V2Link): string;
     /**
-     * Reset performance metrics
+     * Calculate link midpoint (common utility)
      */
-    resetPerformanceMetrics(): void;
+    getLinkMidpoint(link: V2Link): {
+        x: number;
+        y: number;
+    } | null;
     /**
-     * Get current performance metrics
+     * Highlight a node by ID
      */
-    getPerformanceMetrics(): StatsMetrics;
+    highlightNode(nodeId: string): void;
     /**
-     * Force log performance metrics immediately (for debugging)
+     * Highlight multiple nodes by IDs
      */
-    forceLogMetrics(): void;
+    highlightNodes(nodeIds: string[]): void;
     /**
-     * Check if a node is currently hovered
+     * Remove highlight from a node
      */
-    private isNodeHovered;
+    unhighlightNode(nodeId: string): void;
     /**
-     * Check if a link is currently hovered (either directly or through associated node hover)
+     * Clear all node highlights
      */
-    private isLinkHovered;
+    clearHighlights(): void;
     /**
-     * Check if a node is currently selected
+     * Check if a node is highlighted
      */
-    private isNodeSelected;
+    isNodeHighlighted(nodeId: string): boolean;
     /**
-     * Check if a link is currently selected
+     * Get all highlighted node IDs
      */
-    private isLinkSelected;
+    getHighlightedNodes(): Set<string>;
     /**
-     * Check if a link's label should be visible due to selection
-     * (either the link itself is selected, or its connected node is selected)
+     * Clear state cache for a specific node
      */
-    private shouldShowLinkLabelForSelection;
+    private clearSingleNodeStateCache;
     /**
-     * Calculate midpoint of a link for label positioning
+     * Get statistics about cached state
      */
-    private getLinkMidpoint;
+    getStats(): {
+        nodeCount: number;
+        linkCount: number;
+        cachedNodeStates: number;
+        cachedLinkStates: number;
+        highlightedNodes: number;
+    };
+    /**
+     * Destroy and clean up all maps
+     */
+    destroy(): void;
+}
+
+/**
+ * V2 Canvas Graph - Renderer (Force-Graph Pattern)
+ *
+ * Clean implementation following force-graph's exact architecture
+ */
+
+declare class Renderer {
+    private config?;
+    private canvasState?;
+    private hoverManager?;
+    private selectionManager?;
+    private styleResolver?;
+    private stateManager;
+    private metricsManager;
+    private interactionResolver;
+    private dragOptimizer;
+    private zIndexRenderer;
+    private zoomRenderer;
+    private hitDetectionRenderer;
+    /**
+     * Initialize the renderer
+     */
+    initialize(config: {
+        nodes: V2Node[];
+        links: V2Link[];
+        interaction?: InteractionConfig;
+    }, canvasState: CanvasState, hoverManager: HoverManager, selectionManager?: SelectionManager): void;
+    /**
+     * Initialize the optimized z-index renderer with all required dependencies
+     */
+    private initializeZIndexRenderer;
+    /**
+     * Initialize the zoom renderer for zoom-specific optimizations
+     */
+    private initializeZoomRenderer;
     /**
-     * Render directed link with arrow head
+     * Initialize the hit detection renderer for shadow canvas
      */
-    private renderDirectedLink;
+    private initializeHitDetectionRenderer;
     /**
-     * V1-compatible link shortening for source point
+     * Initialize the drag optimizer for fast drag rendering
      */
-    private getShortenedSourcePoint;
+    private initializeDragOptimizer;
     /**
-     * V1-compatible link shortening for target point
+     * Main render method with performance metrics (Instrumented)
+     */
+    render(): void;
+    /**
+     * Render with transform (called during zoom/pan) - OPTIMIZED PATTERN
+     * Fast rendering during zoom, full rendering when stopped
+     */
+    renderWithTransform(): void;
+    /**
+     * Set zoom state for performance optimization (delegates to ZoomRenderer)
+     */
+    setZoomState(isZooming: boolean): void;
+    /**
+     * Set drag state for performance optimization (like setZoomState)
      */
-    private getShortenedTargetPoint;
+    setDragState(isDragging: boolean): void;
     /**
-     * Render arrow head at specific points
+     * Set the currently dragged node
      */
-    private renderArrowAtPoint;
+    setDraggedNode(draggedNode: V2Node): void;
     /**
-     * Render arrow head (legacy method for backward compatibility)
+     * Render shadow canvas for hit detection (delegates to HitDetectionRenderer)
      */
-    private renderArrow;
+    renderShadowCanvas(): void;
+    /**
+     * Mark shadow canvas as dirty for next render (delegates to HitDetectionRenderer)
+     */
+    markShadowCanvasDirty(): void;
+    /**
+     * Force shadow canvas render (delegates to HitDetectionRenderer)
+     */
+    forceShadowCanvasRender(): void;
+    /**
+     * Clear canvas context
+     */
+    private clearCanvas;
+    /**
+     * Apply transform to canvas context
+     */
+    private applyTransform;
+    /**
+     * Get unique link ID for tracking (delegates to StateManager)
+     */
+    private getLinkId;
+    /**
+     * Reset performance metrics
+     */
+    resetPerformanceMetrics(): void;
+    /**
+     * Get current performance metrics
+     */
+    getPerformanceMetrics(): StatsMetrics;
+    /**
+     * Force log performance metrics immediately (for debugging)
+     */
+    forceLogMetrics(): void;
+    /**
+     * Calculate midpoint of a link for label positioning (delegates to StateManager)
+     */
+    private getLinkMidpoint;
     /**
      * Initialize node positions if needed
      */
@@ -1261,44 +1409,16 @@ declare class Renderer {
         };
     };
     /**
-     * Debug shadow canvas export (force-graph pattern)
+     * Debug shadow canvas export (delegates to HitDetectionRenderer)
      */
     debugShadowCanvas(): void;
-    /**
-     * Build node index for O(1) lookups (Step 3 optimization)
-     */
-    private buildNodeIndex;
-    /**
-     * Get node by ID using O(1) lookup (Step 3 optimization)
-     */
-    private getNodeById;
-    /**
-     * Render with z-index layers (for renderWithTransform)
-     */
-    private renderWithLayers;
-    /**
-     * Render with z-index layers and performance metrics (for main render)
-     */
-    private renderWithLayersAndMetrics;
-    /**
-     * Helper methods for getting current interaction states
-     */
-    private getHoveredNode;
-    private getSelectedNode;
-    private getHoveredLink;
-    private getSelectedLink;
-    /**
-     * Layer-specific rendering methods (render subsets of entities)
-     */
-    private renderNodesWithLabelsLayer;
-    /**
-     * Helper method to truncate labels (copied from NodeLabelsRenderer)
-     */
-    private truncateLabel;
     private renderLinksLayer;
-    private renderLinkLabelsLayer;
     private renderNodesLayer;
     private renderNodeLabelsLayer;
+    /**
+     * Get the state manager for highlight operations
+     */
+    getStateManager(): StateManager;
     /**
      * Destroy renderer and clean up resources
      */
@@ -1458,6 +1578,26 @@ declare class V2Graph implements V2Instance {
      * Draw legend on export canvas
      */
     private drawLegendOnExportCanvas;
+    /**
+     * Highlight a node by ID
+     */
+    highlightNode(nodeId: string): void;
+    /**
+     * Highlight multiple nodes by IDs
+     */
+    highlightNodes(nodeIds: string[]): void;
+    /**
+     * Remove highlight from a node
+     */
+    unhighlightNode(nodeId: string): void;
+    /**
+     * Clear all node highlights
+     */
+    clearHighlights(): void;
+    /**
+     * Get all highlighted node IDs
+     */
+    getHighlightedNodes(): Set<string>;
     /**
      * Destroy the graph and clean up resources
      */
@@ -1468,4 +1608,4 @@ declare class V2Graph implements V2Instance {
  */
 declare function createV2Graph(config: V2Config): V2Instance;
 
-export { type ArrowRenderStyle, type BaseGraphConfig, CanvasManager, type CanvasRenderConfig, type CanvasState, type ControlsController, type Coordinates, DEFAULT_COLORS, DEFAULT_HOVER_STYLES, DEFAULT_LINK_LABEL_STYLE, DEFAULT_LINK_STYLE, type DragConfig, type DragInteractionConfig, DragManager, type DragState, ErrorHandler, type GraphControlsConfig, type GraphControlsOrientation, type GraphControlsPosition, type GraphInteractionConfig, type GraphLink, type GraphNode, type GraphNodeWithInitial, type GraphTooltipTheme, type HoverEvent, type HoverInteractionConfig, HoverManager, type HoverState, type HoverStyles, type IconName, type IconSvgName, type InteractionColors, type InteractionConfig, type LegendConfig, type LegendPosition, type LinkArrowStyle, type LinkColors, type LinkLabelRenderStyle, type LinkLabelStyle, type LinkRenderStyle, type LinkSelectHandler, type LinkStyle, NeutralColor, type NodeColorPalette, type NodeLabelRenderStyle, type NodeRenderStyle, type NodeSelectHandler, type NodeStyle, type Orientation, type PhysicsConfig, PhysicsManager, PointerManager, type PointerState, type Position, PrimaryColor, type RenderStyles, Renderer, type ResolvedLinkLabelStyle, type ResolvedLinkStyle, SecondaryColor, type SelectionEvent, type SelectionInteractionConfig, SelectionManager, type SelectionState, type SimulationConfig, StandardColor, type TooltipInteractionConfig, type TooltipPlacement, type UIColors, type V2Config, V2Graph, type V2Instance, type V2Link, type V2Node, ValidationError, type ZoomConfig, ZoomManager, createV2Graph, getIcon, getIconSvg, iconSvg, icons, isValidLinkStyle, isValidNodeStyle, mergeLinkStyle, mergeNodeStyle };
+export { type ArrowRenderStyle, type BaseGraphConfig, CanvasManager, type CanvasRenderConfig, type CanvasState, type ControlsController, type Coordinates, DEFAULT_COLORS, DEFAULT_HOVER_STYLES, DEFAULT_LINK_LABEL_STYLE, DEFAULT_LINK_STYLE, type DragConfig, type DragInteractionConfig, DragManager, type DragState, ErrorHandler, type GraphControlsConfig, type GraphControlsOrientation, type GraphControlsPosition, type GraphInteractionConfig, type GraphLink, type GraphNode, type GraphNodeWithInitial, type GraphTooltipTheme, type HighlightInteractionConfig, type HoverEvent, type HoverInteractionConfig, HoverManager, type HoverState, type HoverStyles, type IconName, type IconSvgName, type InteractionColors, type InteractionConfig, type LegendConfig, type LegendPosition, type LinkArrowStyle, type LinkColors, type LinkLabelRenderStyle, type LinkLabelStyle, type LinkRenderStyle, type LinkSelectHandler, type LinkStyle, NeutralColor, type NodeColorPalette, type NodeLabelRenderStyle, type NodeRenderStyle, type NodeSelectHandler, type NodeStyle, type Orientation, type PhysicsConfig, PhysicsManager, PointerManager, type PointerState, type Position, PrimaryColor, type RenderStyles, Renderer, type ResolvedLinkLabelStyle, type ResolvedLinkStyle, SecondaryColor, type SelectionEvent, type SelectionInteractionConfig, SelectionManager, type SelectionState, type SimulationConfig, StandardColor, type TooltipInteractionConfig, type TooltipPlacement, type UIColors, type V2Config, V2Graph, type V2Instance, type V2Link, type V2Node, ValidationError, type ZoomConfig, ZoomManager, createV2Graph, getIcon, getIconSvg, iconSvg, icons, isValidLinkStyle, isValidNodeStyle, mergeLinkStyle, mergeNodeStyle };