polly-graph 0.1.7 → 0.1.8

package/dist/index.d.ts

@@ -1,4 +1,5 @@
-import { SimulationNodeDatum, SimulationLinkDatum } from 'd3-force';
+import { SimulationNodeDatum, SimulationLinkDatum, Simulation } from 'd3-force';
+import { Selection } from 'd3-selection';
 
 interface Coordinates {
     readonly x: number;
@@ -32,7 +33,7 @@ interface LegendConfig {
     readonly enabled?: boolean;
     readonly title?: string;
     readonly position?: LegendPosition;
-    readonly items: LegendItem[];
+    readonly items?: LegendItem[];
     readonly collapsible?: boolean;
     readonly defaultExpanded?: boolean;
 }
@@ -85,6 +86,101 @@ interface LinkStyle {
     readonly arrow?: LinkArrowStyle;
     readonly label?: LinkLabelStyle;
 }
+interface ResolvedLinkLabelStyle {
+    readonly enabled: boolean;
+    readonly visibility: 'always' | 'hover' | 'selection';
+    readonly backgroundFill: string;
+    readonly borderColor: string;
+    readonly borderWidth: number;
+    readonly borderRadius: number;
+    readonly textColor: string;
+    readonly fontSize: number;
+    readonly paddingX: number;
+    readonly paddingY: number;
+    readonly height: number;
+}
+interface ResolvedLinkStyle {
+    readonly stroke: string;
+    readonly strokeWidth: number;
+    readonly opacity: number;
+    readonly dashArray: string | undefined;
+    readonly arrow: {
+        readonly enabled: boolean;
+        readonly size: number;
+        readonly fill: string;
+    };
+    readonly label: ResolvedLinkLabelStyle;
+}
+
+interface LinkForceConfig {
+    readonly enabled?: boolean;
+    readonly distance?: number | ((link: GraphLink) => number);
+    readonly strength?: number | ((link: GraphLink) => number);
+    readonly iterations?: number;
+}
+interface ChargeForceConfig {
+    readonly enabled?: boolean;
+    readonly strength?: number | ((node: GraphNode) => number);
+    readonly theta?: number;
+    readonly distanceMin?: number;
+    readonly distanceMax?: number;
+}
+interface CollideForceConfig {
+    readonly enabled?: boolean;
+    readonly radius?: number | ((node: GraphNode) => number);
+    readonly strength?: number;
+    readonly iterations?: number;
+}
+interface CenterForceConfig {
+    readonly enabled?: boolean;
+    readonly strength?: number;
+    readonly x?: number;
+    readonly y?: number;
+}
+interface XForceConfig {
+    readonly enabled?: boolean;
+    readonly strength?: number;
+    readonly x?: number | ((node: GraphNode) => number);
+}
+interface YForceConfig {
+    readonly enabled?: boolean;
+    readonly strength?: number;
+    readonly y?: number | ((node: GraphNode) => number);
+}
+interface SimulationForces {
+    readonly link?: LinkForceConfig;
+    readonly charge?: ChargeForceConfig;
+    readonly collide?: CollideForceConfig;
+    readonly center?: CenterForceConfig;
+    readonly x?: XForceConfig;
+    readonly y?: YForceConfig;
+}
+interface AdaptiveConfig {
+    readonly enabled?: boolean;
+    readonly nodeCountThresholds?: {
+        readonly small?: number;
+        readonly medium?: number;
+        readonly large?: number;
+    };
+}
+interface WarmupConfig {
+    readonly enabled?: boolean;
+    readonly ticks?: number;
+}
+interface CooldownConfig {
+    readonly enabled?: boolean;
+    readonly delay?: number;
+}
+interface EnhancedSimulationConfig {
+    readonly alpha?: number;
+    readonly alphaMin?: number;
+    readonly alphaDecay?: number;
+    readonly velocityDecay?: number;
+    readonly forces?: SimulationForces;
+    readonly adaptive?: AdaptiveConfig;
+    readonly warmup?: WarmupConfig;
+    readonly cooldown?: CooldownConfig;
+}
 
 type GraphTooltipTheme = 'dark' | 'light';
 type TooltipPlacement = 'top' | 'bottom' | 'left' | 'right' | 'auto';
@@ -120,11 +216,7 @@ interface GraphConfig {
     readonly links: GraphLink[];
     readonly autoFit?: boolean;
     readonly responsive?: boolean;
-    readonly simulation?: {
-        readonly alpha?: number;
-        readonly gravity?: number;
-        readonly linkDistance?: number | ((link: GraphLink) => number);
-    };
+    readonly simulation?: EnhancedSimulationConfig;
     readonly interaction?: GraphInteractionConfig;
     readonly controls?: GraphControlsConfig;
     readonly legend?: LegendConfig;
@@ -138,6 +230,7 @@ interface GraphInstance {
     fitView(): void;
     destroy(): void;
     exportGraph(fileName?: string): void;
+    clearSelection(): void;
     on(event: 'nodeSelect', handler: (node: GraphNode, element: SVGCircleElement) => void): () => void;
     on(event: 'nodeDeselect', handler: (node: GraphNode, element: SVGCircleElement) => void): () => void;
     on(event: 'linkSelect', handler: (link: GraphLink, element: SVGLineElement) => void): () => void;
@@ -148,6 +241,388 @@ interface GraphInstance {
     off(event: 'linkDeselect', handler: (link: GraphLink, element: SVGLineElement) => void): void;
 }
 
+/**
+ * Main Graph Factory - Creates and manages a graph instance
+ *
+ * Clean modular architecture:
+ * - GraphManager: State management and coordination
+ * - RenderPipeline: Rendering workflow
+ * - InteractionManager: User interactions
+ */
 declare function createGraph(config: GraphConfig): GraphInstance;
 
-export { type GraphConfig, type GraphInstance, type GraphInteractionConfig, type GraphLink, type GraphNode, createGraph };
+/**
+ * Comprehensive validation system for framework-independent graph configuration.
+ * Provides runtime validation to catch integration errors early.
+ */
+
+interface ValidationError {
+    readonly field: string;
+    readonly message: string;
+    readonly value: unknown;
+    readonly code: string;
+}
+interface ValidationResult {
+    readonly isValid: boolean;
+    readonly errors: ValidationError[];
+    readonly warnings: string[];
+}
+declare class GraphValidator {
+    /**
+     * Validate complete graph configuration
+     */
+    static validateConfig(config: GraphConfig): ValidationResult;
+    /**
+     * Validate container element
+     */
+    private static validateContainer;
+    /**
+     * Validate graph nodes
+     */
+    private static validateNodes;
+    /**
+     * Validate graph links
+     */
+    private static validateLinks;
+    /**
+     * Validate interaction configuration
+     */
+    private static validateInteraction;
+    /**
+     * Validate node style
+     */
+    private static validateNodeStyle;
+    /**
+     * Validate runtime environment
+     */
+    static validateEnvironment(): ValidationResult;
+}
+/**
+ * Validation error for framework integrations
+ */
+declare class GraphValidationError extends Error {
+    readonly errors: ValidationError[];
+    readonly warnings: string[];
+    constructor(result: ValidationResult);
+}
+
+/**
+ * Centralized error handling for framework-independent graph operations.
+ * Provides graceful degradation and helpful error messages.
+ */
+
+interface ErrorContext {
+    readonly operation: string;
+    readonly component?: string;
+    readonly data?: unknown;
+}
+declare class GraphError extends Error {
+    readonly code: string;
+    readonly context: ErrorContext;
+    readonly recoverable: boolean;
+    constructor(message: string, code: string, context: ErrorContext, recoverable?: boolean);
+}
+declare class ErrorHandler {
+    private static isDestroyed;
+    /**
+     * Handle errors with appropriate logging and recovery
+     */
+    static handle(error: Error, context: ErrorContext, fallback?: () => void): void;
+    /**
+     * Wrap async operations with error handling
+     */
+    static wrapAsync<T>(operation: () => Promise<T>, context: ErrorContext, fallback?: () => T): Promise<T>;
+    /**
+     * Wrap synchronous operations with error handling
+     */
+    static wrap<T>(operation: () => T, context: ErrorContext, fallback?: () => T): T | undefined;
+    /**
+     * Safe DOM operation wrapper
+     */
+    static safeDOMOperation<T>(operation: () => T, context: ErrorContext, fallback?: () => T): T | undefined;
+    /**
+     * Safe D3 operation wrapper
+     */
+    static safeD3Operation<T>(operation: () => T, context: ErrorContext, fallback?: () => T): T | undefined;
+    /**
+     * Create recoverable error for non-critical failures
+     */
+    static createRecoverableError(message: string, code: string, context: ErrorContext): GraphError;
+    /**
+     * Create non-recoverable error for critical failures
+     */
+    static createCriticalError(message: string, code: string, context: ErrorContext): GraphError;
+    /**
+     * Validate and handle D3 selection operations
+     */
+    static validateSelection<T extends {
+        size(): number;
+    }>(selection: T | null | undefined, context: ErrorContext, operation: (sel: T) => void): void;
+    /**
+     * Handle simulation errors with graceful degradation
+     */
+    static handleSimulationError(error: Error, context: ErrorContext, simulation?: Simulation<GraphNode, GraphLink>): void;
+    /**
+     * Mark error handler as destroyed to prevent further operations
+     */
+    static destroy(): void;
+    /**
+     * Reset error handler state
+     */
+    static reset(): void;
+}
+
+/**
+ * Framework-independent event emitter for graph events.
+ * Provides better TypeScript support and event namespacing than manual Set management.
+ */
+
+type EventListener<T> = (data: T, element?: Element) => void;
+interface EventUnsubscribe {
+    (): void;
+}
+interface EventEmitterOptions {
+    readonly maxListeners?: number;
+    readonly enableWarnings?: boolean;
+}
+declare class GraphEventEmitter<TEventMap extends Record<string, unknown>> {
+    private readonly listeners;
+    private readonly options;
+    private isDestroyed;
+    private listenerIdCounter;
+    constructor(options?: EventEmitterOptions);
+    /**
+     * Add an event listener
+     */
+    on<TEvent extends keyof TEventMap>(event: TEvent, listener: EventListener<TEventMap[TEvent]>, namespace?: string): EventUnsubscribe;
+    /**
+     * Add a one-time event listener
+     */
+    once<TEvent extends keyof TEventMap>(event: TEvent, listener: EventListener<TEventMap[TEvent]>, namespace?: string): EventUnsubscribe;
+    /**
+     * Remove a specific listener
+     */
+    off<TEvent extends keyof TEventMap>(event: TEvent, listener: EventListener<TEventMap[TEvent]>): void;
+    /**
+     * Remove listener by ID
+     */
+    private removeListener;
+    /**
+     * Remove all listeners for an event or namespace
+     */
+    removeAllListeners<TEvent extends keyof TEventMap>(event?: TEvent, namespace?: string): void;
+    /**
+     * Emit an event to all listeners
+     */
+    emit<TEvent extends keyof TEventMap>(event: TEvent, data: TEventMap[TEvent], element?: Element): boolean;
+    /**
+     * Get the number of listeners for an event
+     */
+    listenerCount<TEvent extends keyof TEventMap>(event: TEvent): number;
+    /**
+     * Get all event names that have listeners
+     */
+    eventNames(): Array<keyof TEventMap>;
+    /**
+     * Get listeners for an event
+     */
+    getListeners<TEvent extends keyof TEventMap>(event: TEvent): Array<EventListener<TEventMap[TEvent]>>;
+    /**
+     * Check if an event has listeners
+     */
+    hasListeners<TEvent extends keyof TEventMap>(event: TEvent): boolean;
+    /**
+     * Get debug information about the emitter
+     */
+    getDebugInfo(): {
+        totalEvents: number;
+        totalListeners: number;
+        events: {
+            [k: string]: number;
+        };
+        namespaces: {
+            [k: string]: number;
+        };
+        isDestroyed: boolean;
+    };
+    /**
+     * Clean up all listeners and mark as destroyed
+     */
+    destroy(): void;
+    /**
+     * Reset the emitter (clear listeners but allow new ones)
+     */
+    reset(): void;
+}
+/**
+ * Graph-specific event types
+ */
+interface GraphEventMap {
+    'nodeSelect': {
+        node: GraphNode;
+        element: SVGCircleElement;
+    };
+    'nodeDeselect': {
+        node: GraphNode;
+        element: SVGCircleElement;
+    };
+    'linkSelect': {
+        link: GraphLink;
+        element: SVGLineElement;
+    };
+    'linkDeselect': {
+        link: GraphLink;
+        element: SVGLineElement;
+    };
+    'graphRender': {
+        nodeCount: number;
+        linkCount: number;
+    };
+    'simulationStart': {
+        alpha: number;
+    };
+    'simulationEnd': {
+        iterations: number;
+    };
+    'zoomStart': {
+        scale: number;
+        x: number;
+        y: number;
+    };
+    'zoomEnd': {
+        scale: number;
+        x: number;
+        y: number;
+    };
+    [key: string]: unknown;
+}
+type GraphEventName = keyof GraphEventMap;
+/**
+ * Type-safe graph event emitter
+ */
+declare class TypedGraphEventEmitter extends GraphEventEmitter<GraphEventMap> {
+    constructor(options?: EventEmitterOptions);
+}
+
+interface GraphLayers {
+    readonly svg: SVGSVGElement;
+    readonly overlay: HTMLDivElement;
+    readonly interactionLayer: SVGGElement;
+    readonly interactionRect: SVGRectElement;
+    readonly root: SVGGElement;
+    readonly links: SVGGElement;
+    readonly nodeRings: SVGGElement;
+    readonly nodes: SVGGElement;
+    readonly nodeLabels: SVGGElement;
+    readonly linkLabels: SVGGElement;
+    readonly hoverLayer: {
+        readonly container: SVGGElement;
+        readonly links: SVGGElement;
+        readonly nodes: SVGGElement;
+        readonly nodeLabels: SVGGElement;
+        readonly linkLabels: SVGGElement;
+    };
+    readonly selectionLayer: {
+        readonly container: SVGGElement;
+        readonly links: SVGGElement;
+        readonly nodes: SVGGElement;
+        readonly nodeLabels: SVGGElement;
+        readonly linkLabels: SVGGElement;
+    };
+}
+
+interface RenderableGraphLink {
+    readonly link: GraphLink;
+    readonly style: ResolvedLinkStyle;
+    readonly markerEnd: string;
+}
+
+/**
+ * Centralized selection management for graph nodes and links.
+ * Simplifies selection logic and ensures consistent behavior.
+ */
+
+interface SelectionState {
+    selectedNode: {
+        element: SVGCircleElement;
+        data: GraphNode;
+    } | null;
+    selectedLink: {
+        element: SVGLineElement;
+        data: GraphLink;
+        originalMarker: string | null;
+    } | null;
+}
+declare class SelectionManager {
+    private state;
+    private readonly eventEmitter;
+    private readonly config;
+    private readonly layers;
+    private readonly linkMarkerSnapshots;
+    private readonly root;
+    constructor(eventEmitter: TypedGraphEventEmitter, config: SelectionInteractionConfig, layers: GraphLayers, linkMarkerSnapshots: Map<SVGLineElement, string | null>, root: Selection<SVGGElement, unknown, null, undefined>);
+    /**
+     * Select a node, automatically deselecting any current selection
+     */
+    selectNode(nodeElement: SVGCircleElement, nodeData: GraphNode): void;
+    /**
+     * Select a link, automatically deselecting any current selection
+     */
+    selectLink(linkElement: SVGLineElement, renderableLink: RenderableGraphLink, event?: MouseEvent): void;
+    /**
+     * Deselect the currently selected node
+     */
+    private deselectNode;
+    /**
+     * Deselect the currently selected link
+     */
+    private deselectLink;
+    /**
+     * Clear all selections
+     */
+    clearSelection(): void;
+    /**
+     * Get current selection state
+     */
+    getSelectionState(): SelectionState;
+    /**
+     * Check if a specific node is selected
+     */
+    isNodeSelected(nodeData: GraphNode): boolean;
+    /**
+     * Check if a specific link is selected
+     */
+    isLinkSelected(linkData: GraphLink): boolean;
+    /**
+     * Handle click on background (deselect all)
+     */
+    handleBackgroundClick(event: MouseEvent, svg: SVGSVGElement, interactionRect: SVGRectElement): void;
+    /**
+     * Bring node and related elements to front using selection layer sub-layers
+     */
+    private bringNodeToFront;
+    /**
+     * Bring link and its label to front using selection layer
+     */
+    private bringLinkToFront;
+    /**
+     * Restore elements back to their original layers
+     */
+    private restoreSelectedElements;
+    /**
+     * Utility method to bring any SVG element to front using appendChild
+     * Based on the reference implementation pattern
+     */
+    private bringElementToFront;
+    /**
+     * Clear hover state to prevent conflicts with selection
+     * Similar to the clearAllHoverLayers function in create-node-hover.ts
+     */
+    private clearHoverState;
+    /**
+     * Clean up resources
+     */
+    destroy(): void;
+}
+
+export { type ErrorContext, ErrorHandler, type EventUnsubscribe, type GraphConfig, type GraphControlsConfig, GraphError, type GraphEventMap, type GraphEventName, type GraphInstance, type GraphInteractionConfig, type GraphLink, type GraphNode, GraphValidationError, GraphValidator, type LegendConfig, SelectionManager, type SelectionState, TypedGraphEventEmitter, type ValidationError, type ValidationResult, createGraph };