energy-visualization-sankey 1.0.0

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

@@ -0,0 +1,149 @@
+import type { BoxMaxes, BoxTops, SummaryData, YearFlows, YearLabels, YearSums, YearTotals } from '@/types';
+import { DataService } from '@/services/data/DataService';
+import { ConfigurationService } from "@/services/ConfigurationService";
+/**
+ * Summary Service Implementation
+ *
+ * Processes raw energy data into
+ * totals, flows, labels, and statistical summaries needed for visualization.
+ *
+ * Include comprehensive multi-layer caching.
+ * Handles complex mathematical operations for energy flow summary data including
+ * totals calculation, maximum value detection, and statistical analysis.
+ *
+ * Mathematical Operations:
+ * - Fuel totals calculation across all consumption sectors
+ * - Sector totals calculation across all fuel types
+ * - Maximum value detection for scaling calculations
+ * - Box positioning calculations for visual layout
+ * - Flow data preparation for animation sequences
+ */
+export declare class SummaryService {
+    private dataService;
+    private configService;
+    summary: SummaryData | null;
+    totals: YearTotals[];
+    flows: YearFlows[];
+    labels: YearLabels[];
+    yearSums: YearSums;
+    maxes: BoxMaxes;
+    boxTops: BoxTops | null;
+    constructor(dataService: DataService, configService: ConfigurationService);
+    /**
+     * Extract expensive calculation to separate method (same logic as original)
+     */
+    private buildSummary;
+    /**
+     * Calculate Energy Flow Totals - Triple Nested Loop Algorithm
+     *
+     * MATHEMATICAL COMPLEXITY: O(n³) where n = years × fuels × sectors
+     * This is the most computationally expensive method in the entire application,
+     * processing every combination of Year × Fuel × Consumption Sector.
+     *
+     * ALGORITHM STRUCTURE:
+     *
+     * Level 1 (i): Years Loop - Process each chronological data point
+     *   └─ Iterates through energy data points from 1800-2021+
+     *   └─ Creates YearTotals, YearFlows, YearLabels structures for each year
+     *
+     * Level 2 (j): Fuels Loop - Process each energy source type
+     *   └─ solar, nuclear, hydro, wind, geo, gas, coal, bio, petro
+     *   └─ Skips electricity (j=0) as it's processed separately
+     *   └─ Calculates fuel totals and label positioning
+     *
+     * Level 3 (k): Sectors Loop - Process each consumption category
+     *   └─ elec (electricity), res (residential), ag (agriculture),
+     *   └─ indus (industrial), trans (transportation)
+     *   └─ Performs cross-tabulation: fuel → sector energy flows
+     *
+     * MATHEMATICAL OPERATIONS PER ITERATION:
+     * 1. Flow counting: Increment flow counters for non-zero values
+     * 2. Sector totals: Accumulate energy by consumption sector
+     * 3. Fuel totals: Accumulate energy by fuel source type
+     * 4. Electricity integration: Add electricity to non-elec sectors
+     * 5. Waste heat calculation: Always include waste heat values
+     * 6. Label positioning: Calculate visual label Y-coordinates
+     * 7. Height accumulation: Track fuel stack heights for layout
+     *
+     * PERFORMANCE OPTIMIZATIONS (LAYER 3 CACHING):
+     * - Configuration constants cached locally (eliminates property access)
+     * - Direct array access patterns optimized for V8 engine
+     * - Type assertions used sparingly to maintain performance
+     * - Mathematical operations use compound assignment for speed
+     *
+     * ENERGY INDUSTRY DOMAIN LOGIC:
+     * - Electricity is treated as both fuel source AND consumption vector
+     * - Waste heat represents thermodynamic losses in electricity generation
+     * - Cross-tabulation enables Sankey flow visualization of energy paths
+     * - Sector totals enable proportional box sizing in visual representation
+     *
+     * EXAMPLE CALCULATION FLOW:
+     * Year 2021, Coal, Industrial Sector:
+     * 1. coal.indus = 15.6 (Quads) - Raw data value
+     * 2. total.indus += 15.6 - Add to industrial sector total
+     * 3. total.coal += 15.6 - Add to coal fuel total
+     * 4. flow.indus++ - Increment industrial flow count
+     * 5. Electricity waste heat added if applicable
+     *
+     * VISUALIZATION MATHEMATICS:
+     * - SCALE (0.02): Converts energy units (Quads) to pixel heights
+     * - LEFT_GAP: Visual spacing between fuel source boxes
+     * - ELEC_BOX positioning: Special coordinate system for electricity flows
+     * - Label positioning: Y-coordinates calculated for fuel source labels
+     */
+    buildTotals(): void;
+    /**
+     * Calculate Maximum Energy Values - Statistical Analysis with Caching
+     *
+     * MATHEMATICAL PURPOSE:
+     * Determines the maximum energy consumption value for each sector across all years.
+     * Critical for proportional visualization - largest values determine visual scale.
+     *
+     * ALGORITHM: Statistical Maximum Detection
+     * For each consumption sector (res, ag, indus, trans, elec):
+     * 1. Extract all year values for that sector: [1970: 15.2, 1980: 18.4, ...]
+     * 2. Apply Math.max() to find peak consumption year
+     * 3. Cache result to avoid repeated Math.max() calls (expensive operation)
+     *
+     * VISUALIZATION APPLICATION:
+     * Max values determine box heights in Sankey diagram:
+     * - Residential sector max → residential box height scale
+     * - Industrial sector max → industrial box height scale
+     * - Transportation sector max → transportation box height scale
+     *
+     */
+    private buildMaxes;
+    /**
+     * Calculate Consumption Sector Box Positions - Layout Algorithm with Caching
+     *
+     * MATHEMATICAL PURPOSE:
+     * Calculates Y-coordinate positions for consumption sector boxes in the right-hand column
+     * of the Sankey diagram. Each box position depends on the cumulative heights of boxes above it.
+     *
+     * LAYOUT ALGORITHM: Sequential Stacking with Proportional Heights
+     * 1. Start with residential (res) box at base position: ELEC_BOX[1] + 50
+     * 2. Each subsequent box stacks below with: previous_top + previous_max_height + gap
+     * 3. Box heights are proportional to maximum energy consumption (maxes values)
+     * 4. Visual gaps (RIGHT_GAP) separate boxes for clarity
+     *
+     * MATHEMATICAL FORMULA for Box Positioning:
+     * box_top[i] = box_top[i-1] + maxes[i-1] × SCALE + RIGHT_GAP
+     *
+     * Where:
+     * - maxes[sector]: Peak energy consumption for that sector across all years
+     * - SCALE (0.02): Energy-to-pixel conversion factor
+     * - RIGHT_GAP: Visual spacing between consumption boxes
+     *
+     * VISUAL LAYOUT SEQUENCE:
+     * 1. Residential (res):    ELEC_BOX[1] + 50
+     * 2. Agriculture (ag):     res_top + res_max_height + gap
+     * 3. Industrial (indus):   ag_top + ag_max_height + gap
+     * 4. Transportation (trans): indus_top + indus_max_height + gap
+     *
+     * EXAMPLE CALCULATION (SCALE = 0.02, RIGHT_GAP = 15):
+     * res_top = 350, res_max = 30.5 Quads
+     * → ag_top = 350 + (30.5 × 0.02) + 15 = 365.61 pixels
+     */
+    private buildBoxTops;
+}
+//# sourceMappingURL=SummaryService.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"SummaryService.d.ts","sourceRoot":"","sources":["../../../src/services/calculation/SummaryService.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAC,QAAQ,EAAE,OAAO,EAAE,WAAW,EAAE,SAAS,EAAE,UAAU,EAAE,QAAQ,EAAE,UAAU,EAAC,MAAM,SAAS,CAAC;AACzG,OAAO,EAAC,WAAW,EAAC,MAAM,6BAA6B,CAAC;AACxD,OAAO,EAAC,oBAAoB,EAAC,MAAM,iCAAiC,CAAC;AAErE;;;;;;;;;;;;;;;;GAgBG;AACH,qBAAa,cAAc;IAUnB,OAAO,CAAC,WAAW;IACnB,OAAO,CAAC,aAAa;IAVlB,OAAO,EAAE,WAAW,GAAG,IAAI,CAAQ;IACnC,MAAM,EAAE,UAAU,EAAE,CAAM;IAC1B,KAAK,EAAE,SAAS,EAAE,CAAM;IACxB,MAAM,EAAE,UAAU,EAAE,CAAM;IAC1B,QAAQ,EAAE,QAAQ,CAAM;IACxB,KAAK,EAAE,QAAQ,CAAK;IACpB,OAAO,EAAE,OAAO,GAAG,IAAI,CAAQ;gBAG1B,WAAW,EAAE,WAAW,EACxB,aAAa,EAAE,oBAAoB;IAK/C;;OAEG;IACH,OAAO,CAAC,YAAY;IAepB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAyDG;IACI,WAAW;IA4LlB;;;;;;;;;;;;;;;;;;;OAmBG;IACH,OAAO,CAAC,UAAU;IAiBlB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA8BG;IACH,OAAO,CAAC,YAAY;CAwBvB"}

package/dist/services/data/DataService.d.ts

@@ -0,0 +1,167 @@
+import type { EnergyDataPoint } from '@/types';
+import { DataValidationService } from "@/services/data/DataValidationService";
+import { EventBus } from "@/core/events/EventBus";
+import { Logger } from "@/utils/Logger";
+/**
+ * Data Service
+ *
+ * Core data access and management service providing validated, sorted energy data
+ * with comprehensive query capabilities. Handles input validation, data sorting,
+ * year-based navigation, and statistical analysis.
+ *
+ * Provides validated, indexed access to energy flow data with comprehensive
+ * query capabilities and statistical analysis. Maintains data integrity
+ * through immutable structures and validation at construction time.
+ *
+ * Key Responsibilities:
+ * - Input validation and data structure verification
+ * - Chronological data sorting and indexing
+ * - Year-based data retrieval and navigation
+ * - Fuel and sector totals calculation
+ * - Milestone data management
+ * - Dataset statistics and metadata
+ *
+ * Data Structure:
+ * Manages EnergyDataPoint arrays with comprehensive energy flow data
+ * including all major fuel types (solar, nuclear, hydro, wind, etc.)
+ * and consumption sectors (electricity, residential, industrial, etc.)
+ *
+ * Performance Features:
+ * - Immutable data structures for safety
+ * - Pre-computed indices for fast lookups
+ * - Efficient year-based navigation
+ * - Cached statistics calculations
+ *
+ */
+export declare class DataService {
+    private validationService;
+    private eventBus;
+    private logger;
+    readonly data: readonly EnergyDataPoint[];
+    readonly years: readonly number[];
+    readonly yearsLength: number;
+    readonly firstYear: number;
+    readonly lastYear: number;
+    constructor(energyData: EnergyDataPoint[], validationService: DataValidationService, eventBus: EventBus, logger: Logger);
+    /**
+     * Get data for specific year
+     * @param year - Target year to retrieve
+     * @returns Energy data for the specified year, or undefined if not found
+     */
+    getYearData(year: number): EnergyDataPoint | undefined;
+    /**
+     * Get index of year in chronological sequence
+     * @param year - Year to locate
+     * @returns Zero-based index of year, or -1 if not found
+     */
+    getYearIndex(year: number): number;
+    /**
+     * Check if year exists in dataset
+     * @param year - Year to check
+     * @returns True if year has data available
+     */
+    hasYear(year: number): boolean;
+    /**
+     * Get data by chronological index
+     * @param index - Zero-based index in sorted data array
+     * @returns Energy data at specified index, or undefined if out of bounds
+     */
+    getYearDataByIndex(index: number): EnergyDataPoint | undefined;
+    /**
+     * Check if year is valid and within dataset range
+     * @param year - Year to validate
+     * @returns True if year exists and is within valid range
+     */
+    isValidYear(year: number): boolean;
+    /**
+     * Get year range as tuple
+     * @returns Tuple containing [firstYear, lastYear]
+     */
+    getYearRange(): [number, number];
+    /**
+     * Get total number of data points
+     * @returns Count of available years in dataset
+     */
+    getDataCount(): number;
+    /**
+     * Get chronologically next year
+     * @param currentYear - Starting year
+     * @returns Next available year, or null if at end of dataset
+     */
+    getNextYear(currentYear: number): number | null;
+    /**
+     * Get chronologically previous year
+     * @param currentYear - Starting year
+     * @returns Previous available year, or null if at beginning of dataset
+     */
+    getPreviousYear(currentYear: number): number | null;
+    /**
+     * Get energy total for specific year, fuel, and sector combination
+     * @param year - Target year
+     * @param fuel - Fuel type (e.g., 'coal', 'gas', 'solar')
+     * @param sector - Consumption sector (e.g., 'elec', 'trans', 'indus')
+     * @returns Energy value for the specified combination
+     */
+    getTotalForYear(year: number, fuel: string, sector: string): number;
+    /**
+     * Get total energy consumption for specific fuel across all sectors
+     *
+     * **Energy Industry Analysis Method:**
+     * - Aggregates fuel consumption across all end-use sectors
+     * - Provides fuel-specific energy totals for analysis and visualization
+     * - Follows EIA energy accounting standards for sector summation
+     *
+     * @param year - Target year
+     * @param fuel - Fuel type to sum (e.g., 'coal', 'gas', 'solar')
+     * @returns Total energy consumption for fuel across all sectors
+     */
+    getYearTotalForFuel(year: number, fuel: string): number;
+    /**
+     * Get total energy consumption for specific sector across all fuels
+     *
+     * **Sectoral Energy Analysis Method:**
+     * - Aggregates energy consumption by end-use sector across all fuel types
+     * - Handles electricity as both source and consumption (special case logic)
+     * - Provides sectoral energy totals for economic and policy analysis
+     *
+     * @param year - Target year
+     * @param sector - Sector to sum (e.g., 'trans' for transportation)
+     * @returns Total energy consumption for sector across all fuel types
+     */
+    getYearTotalForSector(year: number, sector: string): number;
+    /**
+     * Get historical milestone description for specific year
+     * @param year - Target year
+     * @returns Milestone description string, or undefined if no milestone
+     */
+    getMilestoneForYear(year: number): string | undefined;
+    /**
+     * Get array of all years containing historical milestones
+     * @returns Array of years with milestone data available
+     */
+    getYearsWithMilestones(): number[];
+    /**
+     * Get list of all fuel types available in dataset
+     * @returns Array of fuel type names (e.g., ['solar', 'coal', 'gas'])
+     */
+    getAvailableFuels(): string[];
+    /**
+     * Get list of all consumption sectors available in dataset
+     * @returns Array of sector names (e.g., ['elec', 'trans', 'indus'])
+     */
+    getAvailableSectors(): string[];
+    /**
+     * Get comprehensive statistics about the dataset
+     * Provides metadata useful for analysis, debugging, and performance monitoring
+     * @returns Object containing dataset statistics and metadata
+     */
+    getDataStatistics(): {
+        totalDataPoints: number;
+        yearRange: [number, number];
+        averageYearGap: number;
+        milestonesCount: number;
+        fuelsCount: number;
+        sectorsCount: number;
+    };
+}
+//# sourceMappingURL=DataService.d.ts.map

package/dist/services/data/DataService.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"DataService.d.ts","sourceRoot":"","sources":["../../../src/services/data/DataService.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAC,eAAe,EAAC,MAAM,SAAS,CAAC;AAC7C,OAAO,EAAC,qBAAqB,EAAC,MAAM,uCAAuC,CAAC;AAC5E,OAAO,EAAC,QAAQ,EAAC,MAAM,wBAAwB,CAAC;AAChD,OAAO,EAAC,MAAM,EAAC,MAAM,gBAAgB,CAAC;AAEtC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AACH,qBAAa,WAAW;IAUhB,OAAO,CAAC,iBAAiB;IACzB,OAAO,CAAC,QAAQ;IAChB,OAAO,CAAC,MAAM;IAVlB,SAAgB,IAAI,EAAE,SAAS,eAAe,EAAE,CAAC;IACjD,SAAgB,KAAK,EAAE,SAAS,MAAM,EAAE,CAAC;IACzC,SAAgB,WAAW,EAAE,MAAM,CAAC;IACpC,SAAgB,SAAS,EAAE,MAAM,CAAC;IAClC,SAAgB,QAAQ,EAAE,MAAM,CAAC;gBAG7B,UAAU,EAAE,eAAe,EAAE,EACrB,iBAAiB,EAAE,qBAAqB,EACxC,QAAQ,EAAE,QAAQ,EAClB,MAAM,EAAE,MAAM;IAgD1B;;;;OAIG;IACI,WAAW,CAAC,IAAI,EAAE,MAAM,GAAG,eAAe,GAAG,SAAS;IAI7D;;;;OAIG;IACI,YAAY,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM;IAIzC;;;;OAIG;IACI,OAAO,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO;IAIrC;;;;OAIG;IACI,kBAAkB,CAAC,KAAK,EAAE,MAAM,GAAG,eAAe,GAAG,SAAS;IAOrE;;;;OAIG;IACI,WAAW,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO;IAOzC;;;OAGG;IACI,YAAY,IAAI,CAAC,MAAM,EAAE,MAAM,CAAC;IAIvC;;;OAGG;IACI,YAAY,IAAI,MAAM;IAI7B;;;;OAIG;IACI,WAAW,CAAC,WAAW,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI;IAQtD;;;;OAIG;IACI,eAAe,CAAC,WAAW,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI;IAW1D;;;;;;OAMG;IACI,eAAe,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,MAAM;IAc1E;;;;;;;;;;;OAWG;IACI,mBAAmB,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM;IAkB9D;;;;;;;;;;;OAWG;IACI,qBAAqB,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,MAAM;IA+BlE;;;;OAIG;IACI,mBAAmB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS;IAK5D;;;OAGG;IACI,sBAAsB,IAAI,MAAM,EAAE;IASzC;;;OAGG;IACI,iBAAiB,IAAI,MAAM,EAAE;IAcpC;;;OAGG;IACI,mBAAmB,IAAI,MAAM,EAAE;IAetC;;;;OAIG;IACI,iBAAiB,IAAI;QACxB,eAAe,EAAE,MAAM,CAAC;QACxB,SAAS,EAAE,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;QAC5B,cAAc,EAAE,MAAM,CAAC;QACvB,eAAe,EAAE,MAAM,CAAC;QACxB,UAAU,EAAE,MAAM,CAAC;QACnB,YAAY,EAAE,MAAM,CAAC;KACxB;CAqBJ"}

package/dist/services/data/DataValidationService.d.ts

@@ -0,0 +1,48 @@
+import type { EnergyDataPoint } from '@/types';
+import { EventBus } from '@/core/events/EventBus';
+import { Logger } from "@/utils/Logger";
+import { ConfigurationService } from "@/services/ConfigurationService";
+/**
+ * Data Validation Service
+ *
+ * Comprehensive validation service ensuring data integrity and structure
+ * compliance for energy flow datasets. Performs multi-level validation
+ * including structure, content, and value range verification.
+ *
+ * Validation Levels:
+ * 1. Structure Validation - Array format and basic structure checks
+ * 2. Content Validation - Required sectors and breakdown verification
+ * 3. Type Validation - Ensures proper data types for all values
+ * 4. Range Validation - Warns about unusual values or potential errors
+ * 5. Duplicate Detection - Prevents duplicate years in dataset
+ *
+ * Error Handling:
+ * Throws DataValidationError with detailed context for failed validations,
+ * including field names, indices, and descriptive error messages.
+ * Emits validation events for service coordination and monitoring.
+ *
+ * Required Data Structure:
+ * Each data point must contain all major fuel types (solar, nuclear, hydro,
+ * wind, geothermal, gas, coal, biomass, petroleum) with consumption
+ * breakdowns across sectors (electricity, residential, agriculture,
+ * industrial, transportation).
+ *
+ * Provides comprehensive validation for energy flow datasets with
+ * multi-level checks ensuring data integrity, proper structure,
+ * and content completeness. Maintains strict validation rules
+ * to prevent downstream calculation errors.
+ */
+export declare class DataValidationService {
+    private configurationService;
+    private eventBus;
+    private logger;
+    constructor(configurationService: ConfigurationService, eventBus: EventBus, logger: Logger);
+    /**
+     * Validate complete data array with comprehensive checks
+     * Performs structure, content, and type validation for entire dataset
+     * @param data - Array of energy data points to validate
+     * @throws DataValidationError - If any validation check fails
+     */
+    validateData(data: EnergyDataPoint[]): void;
+}
+//# sourceMappingURL=DataValidationService.d.ts.map

package/dist/services/data/DataValidationService.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"DataValidationService.d.ts","sourceRoot":"","sources":["../../../src/services/data/DataValidationService.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAC,eAAe,EAAC,MAAM,SAAS,CAAC;AAE7C,OAAO,EAAC,QAAQ,EAAC,MAAM,wBAAwB,CAAC;AAChD,OAAO,EAAC,MAAM,EAAC,MAAM,gBAAgB,CAAC;AACtC,OAAO,EAAC,oBAAoB,EAAC,MAAM,iCAAiC,CAAC;AAErE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,qBAAa,qBAAqB;IAClB,OAAO,CAAC,oBAAoB;IAAwB,OAAO,CAAC,QAAQ;IAAY,OAAO,CAAC,MAAM;gBAAtF,oBAAoB,EAAE,oBAAoB,EAAU,QAAQ,EAAE,QAAQ,EAAU,MAAM,EAAE,MAAM;IAGlH;;;;;OAKG;IACI,YAAY,CAAC,IAAI,EAAE,eAAe,EAAE,GAAG,IAAI;CA4GrD"}

package/dist/types/index.d.ts

@@ -0,0 +1,189 @@
+/**
+ * Type Definitions for Energy Sankey Library
+ *
+ * Comprehensive TypeScript type definitions for energy visualization data structures,
+ * configuration options, service interfaces, and mathematical computation types.
+ *
+ * Key Type Categories:
+ * - Error types: Custom error classes with detailed context
+ * - Data structures: Energy data points, summaries, and flow calculations
+ * - Configuration: Visual constants, fuel definitions, and styling
+ * - Mathematical types: Graph data, positioning, and computational results
+ * - Service interfaces: D3 selections, render data, and layout structures
+ *
+ * Type Safety Features:
+ * - Immutable readonly properties for data integrity
+ * - Strict type constraints for fuel and sector names
+ * - Comprehensive interface coverage for all service operations
+ * - Generic types for flexible service composition
+ *
+ */
+export declare class SankeyError extends Error {
+    code?: string | undefined;
+    constructor(message: string, code?: string | undefined);
+}
+export declare class DataValidationError extends SankeyError {
+    field?: string | undefined;
+    constructor(message: string, field?: string | undefined);
+}
+export interface EnergySectorBreakdown {
+    readonly elec: number;
+    readonly res: number;
+    readonly ag: number;
+    readonly indus: number;
+    readonly trans: number;
+    readonly heat: number;
+    [key: string]: number;
+}
+export interface EnergyDataPoint {
+    readonly year: number;
+    readonly milestone?: string;
+    readonly elec: EnergySectorBreakdown;
+    readonly waste: EnergySectorBreakdown;
+    readonly solar: EnergySectorBreakdown;
+    readonly nuclear: EnergySectorBreakdown;
+    readonly hydro: EnergySectorBreakdown;
+    readonly wind: EnergySectorBreakdown;
+    readonly geo: EnergySectorBreakdown;
+    readonly gas: EnergySectorBreakdown;
+    readonly coal: EnergySectorBreakdown;
+    readonly bio: EnergySectorBreakdown;
+    readonly petro: EnergySectorBreakdown;
+    readonly heat: EnergySectorBreakdown;
+}
+export interface SankeyOptions {
+    readonly data: EnergyDataPoint[];
+    readonly country: string;
+    readonly includeControls?: boolean;
+    readonly includeTimeline?: boolean;
+    readonly includeWasteToggle?: boolean;
+    readonly autoPlay?: boolean;
+    readonly showWasteHeat?: boolean;
+    readonly animationSpeed?: number;
+    readonly width?: number | null;
+    readonly height?: number;
+    readonly loopAnimation?: boolean;
+    readonly debugLogging?: boolean;
+}
+export interface RequiredSankeyOptions extends Required<SankeyOptions> {
+}
+export interface GraphPoint {
+    x: number;
+    y: number;
+}
+export interface GraphStroke {
+    fuel: string;
+    box: string;
+    value: number;
+    stroke: number;
+    a: GraphPoint;
+    b: GraphPoint;
+    c: GraphPoint;
+    d: GraphPoint;
+    cc: GraphPoint;
+}
+export interface GraphData {
+    year: number;
+    graph: GraphStroke[];
+    totals: {
+        [key: string]: number;
+    };
+    offsets: Offest;
+}
+interface OffestX {
+    solar: number;
+    nuclear: number;
+    hydro: number;
+    wind: number;
+    geo: number;
+    gas: number;
+    coal: number;
+    bio: number;
+    petro: number;
+}
+interface OffestY {
+    elec: number;
+    res: number;
+    ag: number;
+    indus: number;
+    trans: number;
+    heat?: number | undefined;
+}
+export interface Offest {
+    x: OffestX;
+    y: OffestY;
+}
+export interface YearTotals {
+    year: number;
+    elec: number;
+    res: number;
+    ag: number;
+    indus: number;
+    trans: number;
+    solar: number;
+    nuclear: number;
+    hydro: number;
+    wind: number;
+    geo: number;
+    gas: number;
+    coal: number;
+    bio: number;
+    petro: number;
+    fuel_height: number;
+    waste: number;
+    heat?: number | undefined;
+    milestone?: any;
+    [key: string]: any;
+}
+export interface YearFlows {
+    year: number;
+    elec: number;
+    res: number;
+    ag: number;
+    indus: number;
+    trans: number;
+    heat?: number | undefined;
+}
+export interface YearLabels {
+    year: number;
+    elec: number;
+    res: number;
+    ag: number;
+    indus: number;
+    trans: number;
+    solar: number;
+    nuclear: number;
+    hydro: number;
+    wind: number;
+    geo: number;
+    gas: number;
+    coal: number;
+    bio: number;
+    petro: number;
+    heat?: number | undefined;
+}
+export interface BoxMaxes {
+    [boxName: string]: number;
+}
+export interface BoxTops {
+    [key: string]: number;
+    res: number;
+    ag: number;
+    indus: number;
+    trans: number;
+}
+export interface YearSums {
+    [year: number]: number;
+}
+export interface SummaryData {
+    totals: YearTotals[];
+    flows: YearFlows[];
+    labels: YearLabels[];
+    maxes: BoxMaxes;
+    boxTops: BoxTops;
+    yearSums: YearSums;
+}
+export type D3SVGSelection = d3.Selection<SVGSVGElement, unknown, HTMLElement, any>;
+export type D3DivSelection = d3.Selection<HTMLDivElement, unknown, HTMLElement, any>;
+export {};
+//# sourceMappingURL=index.d.ts.map

package/dist/types/index.d.ts.map

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

package/dist/utils/Logger.d.ts

@@ -0,0 +1,88 @@
+/**
+ * Performance Monitoring and Debug Logging Utility
+ *
+ * **Performance Monitoring Responsibility:**
+ * - Provides configurable debug logging for performance analysis
+ * - Tracks service initialization, calculation timing, and system events
+ * - Enables production performance monitoring without overhead
+ * - Supports performance regression detection and optimization efforts
+ *
+ * **Debug Logging Architecture:**
+ * - Configuration-controlled logging (debugLogging option)
+ * - Zero performance overhead when disabled (early returns)
+ * - Structured logging levels: log, debug, warn for different diagnostic needs
+ * - Console API integration for browser dev tools compatibility
+ *
+ * **Performance Analysis Features:**
+ * - Timing information: Service initialization, calculation duration
+ * - Cache statistics: Hit rates, cache efficiency metrics
+ * - System events: Service lifecycle, error conditions
+ * - Performance warnings: Threshold-based alerting for slow operations
+ *
+ * **Production Considerations:**
+ * - Logging disabled by default (performance-first approach)
+ * - Minimal memory footprint when disabled
+ * - No sensitive data logging (energy data values excluded)
+ * - Development-friendly: Rich diagnostic information when enabled
+ */
+import { SankeyOptions } from "@/types";
+/**
+ * Logger Implementation
+ *
+ * **Performance-Optimized Logging Service:**
+ * - Configuration-controlled output (respects debugLogging option)
+ * - Early return pattern for zero overhead when disabled
+ * - Console API delegation for browser dev tools integration
+ * - Structured message formatting for diagnostic clarity
+ */
+export declare class Logger {
+    private options;
+    constructor(options: SankeyOptions);
+    /**
+     * General information logging
+     *
+     * **Usage Patterns:**
+     * - Service initialization completion and timing
+     * - Major system milestones (data loaded, services ready)
+     * - Performance metrics (calculation times, cache statistics)
+     * - User interaction events (animation start, year changes)
+     *
+     * **Performance Impact:**
+     * - Zero overhead when debugLogging disabled (early return)
+     * - Minimal string formatting cost when enabled
+     * - Console.log delegation for browser optimization
+     */
+    log(message: string, ...args: any[]): void;
+    /**
+     * Detailed debug information logging
+     *
+     * **Usage Patterns:**
+     * - Algorithm step-by-step tracing
+     * - Cache hit/miss detailed reporting
+     * - Data transformation pipeline debugging
+     * - Complex calculation intermediate results
+     *
+     * **Development Benefits:**
+     * - Granular system behavior visibility
+     * - Algorithm verification and debugging
+     * - Performance bottleneck identification
+     */
+    debug(message: string, ...args: any[]): void;
+    /**
+     * Warning and performance issue logging
+     *
+     * **Usage Patterns:**
+     * - Performance threshold violations (slow initialization)
+     * - Potential optimization opportunities
+     * - Data quality warnings (unusual values)
+     * - System resource constraints
+     *
+     * **Performance Monitoring Integration:**
+     * - Automatic alerting for performance degradation
+     * - Actionable optimization recommendations
+     * - System health status reporting
+     * - Production performance monitoring
+     */
+    warn(message: string, ...args: any[]): void;
+}
+//# sourceMappingURL=Logger.d.ts.map

package/dist/utils/Logger.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Logger.d.ts","sourceRoot":"","sources":["../../src/utils/Logger.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AAEH,OAAO,EAAC,aAAa,EAAC,MAAM,SAAS,CAAC;AAEtC;;;;;;;;GAQG;AACH,qBAAa,MAAM;IAEH,OAAO,CAAC,OAAO;gBAAP,OAAO,EAAE,aAAa;IAG1C;;;;;;;;;;;;;OAaG;IACI,GAAG,CAAC,OAAO,EAAE,MAAM,EAAE,GAAG,IAAI,EAAE,GAAG,EAAE,GAAG,IAAI;IAMjD;;;;;;;;;;;;;OAaG;IACI,KAAK,CAAC,OAAO,EAAE,MAAM,EAAE,GAAG,IAAI,EAAE,GAAG,EAAE,GAAG,IAAI;IAMnD;;;;;;;;;;;;;;OAcG;IACI,IAAI,CAAC,OAAO,EAAE,MAAM,EAAE,GAAG,IAAI,EAAE,GAAG,EAAE,GAAG,IAAI;CAKrD"}