energy-visualization-sankey 1.0.0

package/dist/services/InteractionService.d.ts

@@ -0,0 +1,377 @@
+import { EventBus } from '@/core/events/EventBus';
+import { DataService } from "@/services/data/DataService";
+import { AnimationService } from "@/services/AnimationService";
+import { Logger } from "@/utils/Logger";
+type D3SVGSelection = d3.Selection<SVGSVGElement, unknown, HTMLElement, any>;
+type D3DivSelection = d3.Selection<HTMLDivElement, unknown, HTMLElement, any>;
+interface InteractionState {
+    isMouseDown: boolean;
+    lastMousePosition: {
+        x: number;
+        y: number;
+    };
+    selectedElement: Element | null;
+    isDragging: boolean;
+    touchStartTime: number;
+    keyboardShortcutsEnabled: boolean;
+}
+interface InteractionHandlers {
+    onElementHover?: (element: Element, event: MouseEvent) => void;
+    onElementClick?: (element: Element, event: MouseEvent) => void;
+    onKeyboardNavigation?: (key: string, event: KeyboardEvent) => void;
+    onSliderInteraction?: (value: number, event: Event) => void;
+}
+/**
+ * Interaction Service - Advanced User Interface & Accessibility Management
+ *
+ * ARCHITECTURAL RESPONSIBILITY: Comprehensive User Interaction & Accessibility Framework
+ *
+ * This service implements sophisticated interaction patterns for multi-platform energy
+ * visualization, providing seamless mouse, touch, keyboard, and accessibility support.
+ * Ensures inclusive design principles and responsive user experience across all devices.
+ *
+ * ADVANCED INTERACTION PATTERNS:
+ * 1. **Multi-Modal Input**: Mouse, touch, and keyboard with context switching
+ * 2. **Event Delegation**: Efficient handling of dynamic SVG elements
+ * 3. **Accessibility Integration**: WCAG 2.1 compliance with screen reader support
+ * 4. **Cross-Platform Compatibility**: Desktop, tablet, and mobile optimization
+ * 5. **Performance Optimization**: Event debouncing and efficient listener management
+ * 6. **State Management**: Centralized interaction state for coordinated responses
+ *
+ * USER EXPERIENCE ARCHITECTURE:
+ * - **Mouse Interactions**: Precise hover, click, and drag operations
+ * - **Touch Interactions**: Gesture recognition with mobile-optimized responses
+ * - **Keyboard Navigation**: Full accessibility with arrow keys, space, enter
+ * - **Screen Reader Support**: ARIA labels and semantic markup integration
+ * - **Visual Feedback**: Immediate response to all user interactions
+ *
+ * ACCESSIBILITY FEATURES:
+ * - Keyboard-only navigation through all interactive elements
+ * - Screen reader compatibility with descriptive ARIA labels
+ * - High contrast support and focus management
+ * - Mobile accessibility with proper touch target sizing
+ * - Semantic HTML structure for assistive technologies
+ *
+ * EVENT-DRIVEN INTEGRATION:
+ * Communicates through event bus for loose coupling with other services,
+ * enabling coordinated responses without direct dependencies.
+ */
+export declare class InteractionService {
+    private animationControlService;
+    private dataService;
+    private eventBus;
+    private logger;
+    private state;
+    private handlers;
+    private eventListeners;
+    constructor(animationControlService: AnimationService, dataService: DataService, eventBus: EventBus, logger: Logger);
+    /**
+     * Initialize Comprehensive Multi-Platform User Interactions
+     *
+     * INITIALIZATION RESPONSIBILITY: Complete interaction system setup across all input modalities
+     *
+     * This method orchestrates the setup of all user interaction capabilities, creating
+     * a comprehensive interface layer that supports mouse, touch, keyboard, and accessibility
+     * interactions for the energy visualization.
+     *
+     * MULTI-MODAL INTERACTION INITIALIZATION:
+     * 1. **Mouse Interactions**: Hover effects, click handling, drag operations
+     * 2. **Touch Interactions**: Mobile gestures with responsive feedback
+     * 3. **Keyboard Navigation**: Full accessibility with arrow key navigation
+     * 4. **Slider Controls**: Timeline interaction with precise positioning
+     * 5. **Button Controls**: Play/pause and control button event handling
+     * 6. **Accessibility Features**: WCAG 2.1 compliance with screen reader support
+     *
+     * CROSS-PLATFORM COMPATIBILITY:
+     * Automatically detects device capabilities (touch support, keyboard availability)
+     * and adapts interaction patterns for optimal user experience on each platform.
+     *
+     * EVENT SYSTEM INTEGRATION:
+     * Broadcasts initialization completion to coordinate with other services,
+     * enabling system-wide awareness of interaction capability readiness.
+     */
+    initializeInteractions(svg: D3SVGSelection, tooltip: D3DivSelection): void;
+    /**
+     * Set up mouse event handlers
+     * Provides hover effects, click handling, and drag support
+     */
+    private setupMouseInteractions;
+    /**
+     * Set up touch event handlers
+     * Provides mobile-friendly touch interactions
+     */
+    private setupTouchInteractions;
+    /**
+     * Enable keyboard navigation shortcuts
+     *
+     * **Accessibility Enhancement Responsibility:**
+     * - WCAG 2.1 AA compliance for keyboard navigation
+     * - Document-level keyboard event delegation
+     * - Form input safety (prevents interference)
+     * - Global shortcut system activation
+     *
+     * **Keyboard Navigation Architecture:**
+     * - Document Event Delegation: Single handler for all keyboard events
+     * - Input Safety: Excludes form fields from shortcut processing
+     * - State Management: Prevents duplicate handler registration
+     * - Event System Integration: Coordinates with EventBus
+     *
+     * **Performance Optimization:**
+     * - Single document listener (efficient delegation pattern)
+     * - Early return for duplicate activation
+     * - Form input filtering (performance + UX)
+     *
+     * **Accessibility Standards:**
+     * - Follows ARIA keyboard navigation patterns
+     * - Provides alternative to mouse interaction
+     * - Ensures consistent cross-platform behavior
+     */
+    enableKeyboardNavigation(): void;
+    /**
+     * Disable keyboard navigation
+     *
+     * **Resource Management Responsibility:**
+     * - Graceful keyboard navigation shutdown
+     * - State cleanup coordination
+     * - Memory leak prevention (handlers cleaned by cleanup())
+     *
+     * **Accessibility Pattern:**
+     * - Allows dynamic keyboard navigation toggling
+     * - Maintains system state consistency
+     * - Prepares for service disposal
+     */
+    disableKeyboardNavigation(): void;
+    /**
+     * Handle keyboard navigation events
+     *
+     * **Keyboard Shortcuts Responsibility:**
+     * - Comprehensive animation control via keyboard
+     * - Standard accessibility key mapping
+     * - Cross-platform keyboard compatibility
+     * - Event delegation and custom handler integration
+     *
+     * **Standard Keyboard Mappings (WCAG 2.1 AA):**
+     * - Space/Enter: Play/Pause toggle (standard media controls)
+     * - Arrow Left/Right: Year navigation (standard timeline controls)
+     * - Home/End: First/Last year navigation (standard list navigation)
+     * - Escape: Pause/Stop action (standard escape behavior)
+     *
+     * **Event-Driven Architecture Integration:**
+     * - Emits structured keyboard events to EventBus
+     * - Captures modifier keys (Ctrl, Shift, Alt) for advanced interactions
+     * - Integrates with AnimationService for timeline control
+     * - Supports custom keyboard handlers via callback pattern
+     *
+     * **Accessibility Design Principles:**
+     * - Follows operating system keyboard conventions
+     * - Provides equivalent functionality to mouse interactions
+     * - Preventable default behavior (event.preventDefault())
+     * - Comprehensive modifier key support for power users
+     */
+    private handleKeyboardNavigation;
+    /**
+     * Set up slider interactions
+     *
+     * **Timeline Control Responsibility:**
+     * - Direct year selection via range slider
+     * - Real-time year value feedback
+     * - Smooth animation coordination
+     * - Event-driven timeline synchronization
+     *
+     * **User Control Patterns:**
+     * - HTML5 range input integration (native accessibility)
+     * - Continuous value updates (smooth interaction)
+     * - Animation service coordination (timeline sync)
+     * - Custom event emission (extensibility)
+     *
+     * **Accessibility Features:**
+     * - Native keyboard support (arrow keys, page up/down)
+     * - Screen reader compatibility (range slider semantics)
+     * - Touch-friendly interaction (mobile/tablet support)
+     * - Visual feedback during interaction
+     *
+     * **Performance Considerations:**
+     * - Direct DOM element access (cached reference)
+     * - Efficient value parsing (parseFloat optimization)
+     * - Event delegation pattern (single handler)
+     */
+    private setupSliderInteractions;
+    /**
+     * Set up button interactions
+     *
+     * **Control Button Responsibility:**
+     * - Play/pause animation control
+     * - Speed adjustment controls
+     * - Animation state management
+     * - User feedback coordination
+     *
+     * **User Interface Patterns:**
+     * - Primary action button (play/pause toggle)
+     * - Secondary action buttons (speed controls)
+     * - Event delegation for button groups
+     * - State-aware button behavior
+     *
+     * **Accessibility Integration:**
+     * - Click event handling (mouse + keyboard activation)
+     * - Focus management (keyboard navigation)
+     * - Screen reader button semantics
+     * - Touch-friendly tap targets
+     *
+     * **Animation Control Architecture:**
+     * - Direct AnimationService integration
+     * - State synchronization (playing/paused)
+     * - Speed control coordination
+     * - Event emission for system coordination
+     */
+    private setupButtonInteractions;
+    /**
+     * Set up accessibility features
+     *
+     * **WCAG 2.1 AA Compliance Responsibility:**
+     * - ARIA labels and semantic roles
+     * - Keyboard focus management
+     * - Screen reader support
+     * - Visual focus indicators
+     * - Interactive element accessibility
+     *
+     * **Accessibility Standards Implementation:**
+     * - SVG accessibility (role="img", aria-label)
+     * - Keyboard navigation (tabindex, focus/blur)
+     * - Control accessibility (slider, button roles)
+     * - Focus indicators (visual outline feedback)
+     * - Screen reader descriptions (meaningful labels)
+     *
+     * **Universal Design Principles:**
+     * - Perceivable: Visual focus indicators, semantic structure
+     * - Operable: Keyboard navigation, touch targets
+     * - Understandable: Clear labels, consistent behavior
+     * - Robust: Cross-platform compatibility, assistive technology support
+     *
+     * **Focus Management Architecture:**
+     * - Logical tab order (sequential navigation)
+     * - Visual focus indicators (CSS outline styling)
+     * - Focus trap prevention (proper event handling)
+     * - Screen reader announcements (ARIA integration)
+     */
+    private setupAccessibilityFeatures;
+    /**
+     * Handle element hover events
+     *
+     * **Visual Feedback Responsibility:**
+     * - Interactive element highlighting
+     * - Hover state management
+     * - Multi-element coordination (exclusive hover)
+     * - Event-driven hover notifications
+     *
+     * **User Experience Patterns:**
+     * - Visual Affordance: Immediate hover feedback via CSS classes
+     * - Exclusive Interaction: Single element hover state (removes others)
+     * - Event Context: Rich hover event data (element type, fuel, sector)
+     * - Mouse Position: Coordinates for tooltip positioning
+     *
+     * **Interaction Architecture:**
+     * - CSS Class-Based Styling: .hovered class for visual feedback
+     * - Event Bus Integration: Structured hover events for system coordination
+     * - Custom Handler Support: Extensible hover behavior
+     * - Element Classification: Flow vs Box element detection
+     *
+     * **Performance Considerations:**
+     * - Efficient DOM querying (.hovered class removal)
+     * - Minimal DOM manipulation (add/remove classes)
+     * - Event data extraction (cached attribute access)
+     */
+    private handleElementHover;
+    /**
+     * Handle element click events
+     *
+     * **Selection Management Responsibility:**
+     * - Element selection state management
+     * - Exclusive selection pattern (single selection)
+     * - Visual selection feedback
+     * - Event-driven selection notifications
+     *
+     * **User Interaction Patterns:**
+     * - Click-to-Select: Primary selection mechanism
+     * - Exclusive Selection: Single element selected at a time
+     * - Visual Feedback: .selected class for styling
+     * - Context Preservation: Rich click event data
+     *
+     * **State Management Architecture:**
+     * - CSS Class-Based Selection: .selected class for visual state
+     * - DOM State Management: Clear previous selections
+     * - Event Data Capture: Element type, fuel, sector, coordinates
+     * - Extensible Handler Support: Custom click behavior
+     *
+     * **Integration Benefits:**
+     * - Analytics Support: Click tracking and user behavior
+     * - Tooltip Coordination: Click-based detailed information display
+     * - Custom Behavior: Application-specific selection actions
+     */
+    private handleElementClick;
+    /**
+     * Set custom interaction handlers
+     */
+    setInteractionHandlers(handlers: InteractionHandlers): void;
+    /**
+     * Helper method to add event listener and track for cleanup
+     */
+    private addEventListener;
+    /**
+     * Clean up all interactions and event listeners
+     *
+     * **Resource Management Responsibility:**
+     * - Complete memory cleanup and leak prevention
+     * - Event listener disposal
+     * - State reset and consistency
+     * - DOM class cleanup
+     *
+     * **Memory Management Architecture:**
+     * - Event Listener Cleanup: Remove all tracked listeners to prevent leaks
+     * - State Reset: Return to initial state for consistent disposal
+     * - Handler Clearing: Remove all custom handlers
+     * - DOM Cleanup: Remove visual state classes (.hovered, .selected)
+     *
+     * **Cleanup Pattern Benefits:**
+     * - Memory Leak Prevention: Proper event listener disposal
+     * - State Consistency: Clean slate for reinitialization
+     * - Resource Optimization: Free unused memory and references
+     * - Visual Cleanup: Remove transient UI states
+     *
+     * **Architecture Integration:**
+     * - Service Lifecycle: Proper service disposal pattern
+     * - Event-Driven Cleanup: Coordinated with other services
+     * - DOM State Management: Visual consistency maintenance
+     * - Performance Optimization: Resource deallocation
+     */
+    cleanup(): void;
+    /**
+     * Get current interaction state
+     */
+    getInteractionState(): Readonly<InteractionState>;
+    /**
+     * Check if interactions are enabled
+     */
+    isInteractionEnabled(): boolean;
+    /**
+     * Get interaction statistics
+     */
+    getInteractionStats(): {
+        eventListeners: number;
+        keyboardEnabled: boolean;
+        touchSupported: boolean;
+        lastInteraction: {
+            x: number;
+            y: number;
+        };
+    };
+    /**
+     * Programmatically trigger element hover
+     */
+    triggerElementHover(element: Element): void;
+    /**
+     * Programmatically trigger element click
+     */
+    triggerElementClick(element: Element): void;
+}
+export {};
+//# sourceMappingURL=InteractionService.d.ts.map

package/dist/services/InteractionService.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"InteractionService.d.ts","sourceRoot":"","sources":["../../src/services/InteractionService.ts"],"names":[],"mappings":"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"}

package/dist/services/RenderingService.d.ts

@@ -0,0 +1,152 @@
+import * as d3 from 'd3';
+import { GraphStroke, YearTotals } from '@/types';
+import { EventBus } from '@/core/events/EventBus';
+import { ConfigurationService } from '@/services/ConfigurationService';
+import { SummaryService } from '@/services/calculation/SummaryService';
+import { GraphService } from '@/services/calculation/GraphService';
+import { DataService } from "@/services/data/DataService";
+type D3SVGSelection = d3.Selection<SVGSVGElement, unknown, HTMLElement, any>;
+type D3DivSelection = d3.Selection<HTMLDivElement, unknown, HTMLElement, any>;
+/**
+ * Chart Rendering Service - D3.js SVG Generation & Visual Rendering Engine
+ *
+ * ARCHITECTURAL RESPONSIBILITY: Mathematical Data → Visual SVG Transformation
+ *
+ * This service implements sophisticated D3.js patterns to transform mathematical energy flow
+ * calculations into interactive SVG visualizations. It manages the complete visual rendering
+ * pipeline from raw data to user-ready interactive charts.
+ *
+ * D3.JS DESIGN PATTERNS IMPLEMENTED:
+ * 1. **Selection Patterns**: Efficient DOM element selection and manipulation
+ * 2. **Data Binding**: Binding energy data to SVG elements with enter/update/exit patterns
+ * 3. **Method Chaining**: Fluent D3 API usage for concise and readable code
+ * 4. **Event Handling**: Mouse interactions with tooltip integration
+ * 5. **Transition Management**: Smooth animations for year-to-year transitions
+ * 6. **Scale Management**: Coordinate transformations and responsive scaling
+ *
+ * SVG GENERATION ARCHITECTURE:
+ * - **Fuel Boxes**: Left column showing energy sources (solar, coal, etc.)
+ * - **Sector Boxes**: Right column showing consumption sectors (residential, industrial, etc.)
+ * - **Flow Paths**: connecting fuel sources to consumption sectors
+ * - **Labels & Text**: Dynamic text elements with data-driven content
+ * - **Tooltips**: Interactive information overlays with precise positioning
+ *
+ * VISUAL RENDERING PIPELINE:
+ * Mathematical Data → D3 Selections → SVG Elements → Interactive Features → User Interface
+ *
+ * PERFORMANCE OPTIMIZATIONS:
+ * - Efficient DOM manipulation using D3 selections
+ * - Minimal DOM re-creation during year transitions
+ * - Event delegation for tooltip management
+ * - CSS class-based styling for performance
+ * - Cached line generator for path creation
+ */
+export declare class RenderingService {
+    private configService;
+    private summaryCalculationService;
+    private graphCalculationService;
+    private dataService;
+    private eventBus;
+    private lineGenerator;
+    constructor(configService: ConfigurationService, summaryCalculationService: SummaryService, graphCalculationService: GraphService, dataService: DataService, eventBus: EventBus);
+    /**
+     * Draws the main title, subtitle, and affiliations in separate title container
+     */
+    drawHeader(): void;
+    /**
+     * Draw Fuel Source Labels - Left Column Energy Source Visualization
+     *
+     * RENDERING RESPONSIBILITY: Create dynamic fuel source labels with proportional positioning
+     *
+     * This method implements D3.js text element creation for fuel source identification.
+     * Label positions are calculated dynamically based on energy totals to maintain
+     * accurate visual alignment with proportional fuel box heights.
+     *
+     * D3.JS TEXT RENDERING PATTERNS:
+     * - Dynamic content from configuration and energy data
+     * - Conditional visibility based on energy values (hidden if zero)
+     * - Data attributes for animation and programmatic access
+     * - CSS classes for styling and state management
+     *
+     * PROPORTIONAL POSITIONING ALGORITHM:
+     * Y-position calculated dynamically: TOP_Y + cumulative_energy_heights + gaps
+     * Ensures perfect alignment between fuel labels and their corresponding flow origins
+     */
+    drawLeftLabels(svg: D3SVGSelection, totals: YearTotals): void;
+    /**
+     * Draw Energy Sector Boxes & Labels - Right Column Consumption Visualization
+     *
+     * RENDERING RESPONSIBILITY: Create interactive sector boxes with labels and totals
+     *
+     * This method implements the most complex D3.js element creation patterns, generating
+     * rectangular sector boxes with multi-line labels and dynamic energy totals.
+     * Demonstrates advanced SVG composition with nested text elements.
+     *
+     * ADVANCED D3.JS PATTERNS DEMONSTRATED:
+     * 1. **Conditional Positioning**: Different algorithms for electricity vs. sector boxes
+     * 2. **Complex Text Composition**: Multi-line labels using tspan elements
+     * 3. **Dynamic Sizing**: Proportional box heights based on energy consumption
+     * 4. **Data-Driven Visibility**: Conditional hiding based on energy values
+     * 5. **Nested Element Creation**: Text elements with multiple tspan children
+     * 6. **Special Case Handling**: Residential/Commercial label splitting
+     *
+     * SVG ELEMENT ARCHITECTURE:
+     * Each sector generates: Rectangle (visual box) + Text (label + total + waste)
+     * - Rectangle: Proportionally sized based on energy consumption
+     * - Text Label: Human-readable sector name with special formatting
+     * - Energy Total: Numeric display of energy consumption value
+     * - Waste Total: Thermodynamic losses for electricity-consuming sectors
+     */
+    drawBoxes(svg: D3SVGSelection, totals: YearTotals): void;
+    /**
+     * Draw Interactive Energy Flow Paths - Advanced D3.js SVG Path Rendering
+     *
+     * RENDERING RESPONSIBILITY: Transform Mathematical Flow Data → Interactive SVG Paths
+     *
+     * This method implements the most sophisticated D3.js rendering patterns in the entire
+     * visualization system, creating interactive paths that represent energy
+     * flows between fuel sources and consumption sectors.
+     *
+     * ADVANCED D3.JS PATTERNS IMPLEMENTED:
+     * 1. **Complex Path Generation**: Mathematical GraphStroke data → SVG path strings
+     * 2. **Interactive Event Binding**: Mouse event handlers for tooltip interactions
+     * 3. **Dynamic Content Creation**: Data-driven SVG element creation with unique attributes
+     * 4. **Transition Management**: Smooth fade-in/fade-out tooltip animations
+     * 5. **Context-Aware Selection**: Targeting existing fuel group containers
+     * 6. **Performance Optimization**: Efficient DOM manipulation and event delegation
+     *
+     * ENERGY FLOW VISUALIZATION ARCHITECTURE:
+     * Each energy flow (Fuel → Sector) becomes an SVG <path> element with:
+     * - Geometry calculated by GraphService
+     * - Stroke width proportional to energy quantity (visual data encoding)
+     * - Interactive tooltip showing detailed energy values on hover
+     * - CSS classes enabling styling and animation hooks
+     * - Data attributes for programmatic access and filtering
+     *
+     * TOOLTIP INTERACTION DESIGN:
+     * - Mouseover: 200ms fade-in with energy flow details
+     * - Mouseout: 500ms fade-out for smooth visual transitions
+     * - Dynamic positioning: Follows cursor with offset for readability
+     * - Content formatting: "Fuel → Sector" with numerical energy value
+     *
+     * SVG PATH GENERATION PIPELINE:
+     * Mathematical Coordinates → parseLineData() → SVG Path String → Interactive Path Element
+     */
+    drawFlows(svg: D3SVGSelection, yearIndex: number, tooltip: D3DivSelection): void;
+    /**
+     * Clear chart content
+     */
+    clearChart(svg: D3SVGSelection): void;
+    drawInitialChart(svg: D3SVGSelection, tooltip: D3DivSelection): boolean;
+    /**
+     * Highlight specific fuel flows
+     */
+    highlightFuel(svg: D3SVGSelection, fuelName: string): void;
+    /**
+     * Reset highlighting
+     */
+    resetHighlight(svg: D3SVGSelection): void;
+    parseLineData(stroke: GraphStroke): string;
+}
+export {};
+//# sourceMappingURL=RenderingService.d.ts.map

package/dist/services/RenderingService.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"RenderingService.d.ts","sourceRoot":"","sources":["../../src/services/RenderingService.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,IAAI,CAAC;AACzB,OAAO,EAAa,WAAW,EAAE,UAAU,EAAC,MAAM,SAAS,CAAC;AAC5D,OAAO,EAAC,QAAQ,EAAC,MAAM,wBAAwB,CAAC;AAChD,OAAO,EAAC,oBAAoB,EAAC,MAAM,iCAAiC,CAAC;AACrE,OAAO,EAAC,cAAc,EAAC,MAAM,uCAAuC,CAAC;AACrE,OAAO,EAAC,YAAY,EAAC,MAAM,qCAAqC,CAAC;AACjE,OAAO,EAAC,WAAW,EAAC,MAAM,6BAA6B,CAAC;AAIxD,KAAK,cAAc,GAAG,EAAE,CAAC,SAAS,CAAC,aAAa,EAAE,OAAO,EAAE,WAAW,EAAE,GAAG,CAAC,CAAC;AAC7E,KAAK,cAAc,GAAG,EAAE,CAAC,SAAS,CAAC,cAAc,EAAE,OAAO,EAAE,WAAW,EAAE,GAAG,CAAC,CAAC;AAI9E;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AACH,qBAAa,gBAAgB;IAIrB,OAAO,CAAC,aAAa;IACrB,OAAO,CAAC,yBAAyB;IACjC,OAAO,CAAC,uBAAuB;IAC/B,OAAO,CAAC,WAAW;IACnB,OAAO,CAAC,QAAQ;IAPpB,OAAO,CAAC,aAAa,CAAsB;gBAG/B,aAAa,EAAE,oBAAoB,EACnC,yBAAyB,EAAE,cAAc,EACzC,uBAAuB,EAAE,YAAY,EACrC,WAAW,EAAE,WAAW,EACxB,QAAQ,EAAE,QAAQ;IAQ9B;;OAEG;IACI,UAAU,IAAI,IAAI;IAuEzB;;;;;;;;;;;;;;;;;;OAkBG;IACI,cAAc,CAAC,GAAG,EAAE,cAAc,EAAE,MAAM,EAAE,UAAU,GAAG,IAAI;IAgCpE;;;;;;;;;;;;;;;;;;;;;;;OAuBG;IACI,SAAS,CACZ,GAAG,EAAE,cAAc,EACnB,MAAM,EAAE,UAAU,GACnB,IAAI;IAuFP;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAiCG;IACI,SAAS,CAAC,GAAG,EAAE,cAAc,EAAE,SAAS,EAAE,MAAM,EAAE,OAAO,EAAE,cAAc,GAAG,IAAI;IA0FvF;;OAEG;IACI,UAAU,CAAC,GAAG,EAAE,cAAc,GAAG,IAAI;IAIrC,gBAAgB,CAAC,GAAG,EAAE,cAAc,EAAE,OAAO,EAAE,cAAc,GAAG,OAAO;IAsB9E;;OAEG;IACI,aAAa,CAAC,GAAG,EAAE,cAAc,EAAE,QAAQ,EAAE,MAAM,GAAG,IAAI;IAQjE;;OAEG;IACI,cAAc,CAAC,GAAG,EAAE,cAAc,GAAG,IAAI;IAQzC,aAAa,CAAC,MAAM,EAAE,WAAW,GAAG,MAAM;CAIpD"}

package/dist/services/calculation/GraphService.d.ts

@@ -0,0 +1,111 @@
+import * as d3 from 'd3';
+import { GraphData, GraphPoint } from '@/types';
+import { DataService } from "@/services/data/DataService";
+import { ConfigurationService } from "@/services/ConfigurationService";
+import { SummaryService } from "@/services/calculation/SummaryService";
+/**
+ * Graph Service
+ *
+ * Performs complex mathematical calculations for energy flow positioning and routing.
+ * Handles the sophisticated algorithms needed to calculate Sankey diagram paths,
+ * including triple nested loops for flow positioning and waste heat calculations.
+ *
+ * Key Algorithms:
+ * - Complex flow positioning with mathematical precision
+ * - Waste heat cloning and distribution calculations
+ * - Multi-layer caching system for performance optimization
+ * - D3 line generation for smooth rendering
+ * - Graph data structure management and optimization
+ */
+export declare class GraphService {
+    private configService;
+    private dataService;
+    private summaryCalculationService;
+    graphs: GraphData[];
+    constructor(configService: ConfigurationService, // Will inject when available
+    dataService: DataService, summaryCalculationService: SummaryService);
+    /**
+     * Extract expensive calculation to separate method (same logic as original)
+     */
+    private buildGraphs;
+    /**
+     * Calculate Flow Y-Coordinates - Complex Triple Nested Loop Algorithm
+     *
+     * COMPUTATIONAL COMPLEXITY: O(n³) - Years × Fuels × Sectors
+     * This is the most mathematically sophisticated method in the entire energy visualization system,
+     * handling precise flow positioning, coordinate calculations, and waste heat thermodynamics.
+     *
+     * ALGORITHM STRUCTURE - THREE NESTED LEVELS:
+     *
+     * Level 1 (i): Years Loop - Process each chronological data point
+     *   └─ Creates GraphStroke arrays for energy flow paths
+     *   └─ Manages vertical offset tracking for precise positioning
+     *
+     * Level 2 (j): Fuels Loop - Process each energy source type
+     *   └─ Special handling for electricity (j=0) vs. primary fuels (j>0)
+     *   └─ Calculates fuel-specific positioning and offsets
+     *
+     * Level 3 (k): Sectors Loop - Process each consumption category
+     *   └─ Creates GraphStroke objects for each Fuel → Sector flow
+     *   └─ Applies complex coordinate mathematics for positioning
+     *
+     * CRITICAL COORDINATE MATHEMATICS:
+     * 1. Y-Coordinate Positioning: Uses cumulative offset tracking
+     * 2. Stroke Width Calculation: Energy value × SCALE factor
+     * 3. Control Points: mathematics for smooth flow
+     * 4. Waste Heat Cloning: Deep object cloning with thermodynamic calculations
+     *
+     * WASTE HEAT PHYSICS IMPLEMENTATION:
+     * Implements the fundamental thermodynamic principle that electricity generation
+     * produces waste heat according to Carnot efficiency limits. Each electricity
+     * flow gets a corresponding waste heat flow with identical path geometry.
+     *
+     * COORDINATE SYSTEM DETAILS:
+     * - SCALE (0.02): Converts energy units (Quads) to pixel heights
+     * - ELEC_BOX coordinates: Special positioning for electricity flows
+     * - SR3: Slope ratio for smooth transitions (slope = height/3)
+     * - PATH_GAP: Visual spacing between parallel flow paths
+     * - LEFT_GAP: Spacing between fuel source boxes
+     *
+     * PERFORMANCE OPTIMIZATIONS:
+     * - Method inlining: Configuration constants cached locally
+     * - Direct array indexing: Eliminates object property lookups
+     * - In-place calculations: Minimizes temporary object creation
+     *
+     * MATHEMATICAL PRECISION REQUIREMENTS:
+     * All calculations must maintain sub-pixel precision to ensure:
+     * - Smooth flow animations during year transitions
+     * - Perfect alignment between interconnected flows
+     * - Accurate proportional representation of energy values
+     * - Thermodynamically correct waste heat positioning
+     */
+    calculateGraphY(): void;
+    calculateGraphX(): void;
+    /**
+     * Method Inlined calculateGraphXUps() - eliminates repeated property access
+     */
+    private calculateGraphXUps;
+    /**
+     * Method Inlined calculateGraphXDowns() - eliminates repeated property access
+     */
+    private calculateGraphXDowns;
+    /**
+     * Method Inlined spaceUpsAndDowns() - eliminates repeated property access
+     */
+    spaceUpsAndDowns(): void;
+    /**
+     * Waste heat processing
+     */
+    processWasteHeatFlows(): void;
+    /**
+     * Method Inlined sortGraphUp() - eliminates repeated array access
+     */
+    private sortGraphUp;
+    /**
+     * Method Inlined sortGraphDown() - eliminates repeated array access
+     */
+    private sortGraphDown;
+    sigfig2(n: number | string | undefined | null): number;
+    createLine(): d3.Line<GraphPoint>;
+}
+//# sourceMappingURL=GraphService.d.ts.map

package/dist/services/calculation/GraphService.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"GraphService.d.ts","sourceRoot":"","sources":["../../../src/services/calculation/GraphService.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,IAAI,CAAC;AACzB,OAAO,EAAwB,SAAS,EAAE,UAAU,EAAsB,MAAM,SAAS,CAAC;AAC1F,OAAO,EAAC,WAAW,EAAC,MAAM,6BAA6B,CAAC;AACxD,OAAO,EAAC,oBAAoB,EAAC,MAAM,iCAAiC,CAAC;AACrE,OAAO,EAAC,cAAc,EAAC,MAAM,uCAAuC,CAAC;AAGrE;;;;;;;;;;;;;GAaG;AACH,qBAAa,YAAY;IAIjB,OAAO,CAAC,aAAa;IACrB,OAAO,CAAC,WAAW;IACnB,OAAO,CAAC,yBAAyB;IAL9B,MAAM,EAAE,SAAS,EAAE,CAAM;gBAGpB,aAAa,EAAE,oBAAoB,EAAE,6BAA6B;IAClE,WAAW,EAAE,WAAW,EACxB,yBAAyB,EAAE,cAAc;IAKrD;;OAEG;IACH,OAAO,CAAC,WAAW;IAcnB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAkDG;IACI,eAAe;IAmRf,eAAe;IAMtB;;OAEG;IACH,OAAO,CAAC,kBAAkB;IA8B1B;;OAEG;IACH,OAAO,CAAC,oBAAoB;IA8B5B;;OAEG;IACI,gBAAgB;IA8CvB;;OAEG;IACI,qBAAqB;IA8B5B;;OAEG;IACH,OAAO,CAAC,WAAW;IAoBnB;;OAEG;IACH,OAAO,CAAC,aAAa;IAoBd,OAAO,CAAC,CAAC,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,GAAG,IAAI,GAAG,MAAM;IA+BtD,UAAU,IAAI,EAAE,CAAC,IAAI,CAAC,UAAU,CAAC;CAS3C"}