energy-visualization-sankey 1.0.0

package/jest.config.cjs

@@ -0,0 +1,20 @@
+module.exports = {
+    testEnvironment: 'jsdom',
+    setupFilesAfterEnv: ['<rootDir>/tests/setup.js'],
+    transform: {
+        '^.+\\.(js|jsx)$': 'babel-jest',
+    },
+    testMatch: [
+        '<rootDir>/tests/**/*.test.js'
+    ],
+    moduleFileExtensions: ['js', 'json'],
+    collectCoverageFrom: [
+        'src/**/*.{ts,js}',
+        '!src/**/*.d.ts',
+        '!src/types/**/*'
+    ],
+    // Allow importing the standalone ESM build in tests
+    transformIgnorePatterns: [
+        'node_modules/(?!(d3|internmap)/)'
+    ]
+};

package/package.json

@@ -0,0 +1,68 @@
+{
+  "name": "energy-visualization-sankey",
+  "version": "1.0.0",
+  "description": "A modern TypeScript library for creating interactive Sankey diagrams that visualize energy flows from sources to consumption sectors.",
+  "type": "module",
+  "main": "dist/sankey.umd.js",
+  "module": "dist/sankey.esm.js",
+  "types": "dist/types/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/types/index.d.ts",
+      "import": "./dist/sankey.esm.js",
+      "require": "./dist/sankey.umd.js"
+    },
+    "./styles": "./src/styles/sankey.css"
+  },
+  "scripts": {
+    "dev": "rollup -c -w",
+    "build": "rollup -c",
+    "build:dev": "rollup -c",
+    "type-check": "tsc --noEmit",
+    "clean": "rm -rf dist",
+    "test": "jest",
+    "test:watch": "jest --watch",
+    "test:numerical": "jest tests/numerical-validation.test.js",
+    "test:visual": "node scripts/visual-validation-real-data.js",
+    "test:performance": "node scripts/performance-validation-real.js",
+    "test:ci": "jest --coverage --watchAll=false --passWithNoTests",
+    "validate:baseline": "npm run build && npm run serve & sleep 3 && npm run test:visual && npm run test:performance && kill %1",
+    "validate:quick": "npm run test:numerical",
+    "validate:full": "npm run test:numerical && npm run build && npm run serve & sleep 3 && npm run test:visual && npm run test:performance && kill %1",
+    "validate": "npm run validate:full",
+    "prepublishOnly": "npm run clean && npm run test:ci && npm run build"
+  },
+  "keywords": [
+    "sankey",
+    "energy",
+    "d3js",
+    "typescript",
+    "energy-visualization",
+    "data-visualization"
+  ],
+  "author": "Research Computing Center (RCC) at The University of Chicago",
+  "license": "MIT",
+  "dependencies": {
+    "d3": "^7.8.5"
+  },
+  "devDependencies": {
+    "@babel/core": "^7.23.0",
+    "@babel/preset-env": "^7.23.0",
+    "@rollup/plugin-node-resolve": "^15.2.3",
+    "@rollup/plugin-terser": "^0.4.4",
+    "@rollup/plugin-typescript": "^11.1.5",
+    "@types/d3": "^7.4.0",
+    "@types/jest": "^29.5.0",
+    "babel-jest": "^29.7.0",
+    "jest": "^29.7.0",
+    "jest-environment-jsdom": "^29.7.0",
+    "jsdom": "^22.1.0",
+    "pixelmatch": "^5.3.0",
+    "playwright": "^1.40.0",
+    "pngjs": "^7.0.0",
+    "rollup": "^4.6.1",
+    "rollup-plugin-typescript2": "^0.36.0",
+    "tslib": "^2.6.0",
+    "typescript": "^5.3.0"
+  }
+}

package/rollup.config.js

@@ -0,0 +1,131 @@
+import resolve from '@rollup/plugin-node-resolve';
+import typescript from 'rollup-plugin-typescript2';
+import terser from '@rollup/plugin-terser';
+import ts from 'typescript';
+
+const isDev = process.env.NODE_ENV === 'development';
+
+const baseConfig = {
+    input: 'src/core/Sankey.ts',
+    external: ['d3'], // D3 is external dependency
+    plugins: [
+        resolve({
+            browser: true,
+            preferBuiltins: false
+        }),
+        typescript({
+            tsconfig: './tsconfig.json',
+            useTsconfigDeclarationDir: true,
+            clean: true,
+            abortOnError: false,
+            rollupCommonJSResolveHack: false,
+            typescript: ts
+        })
+    ]
+};
+
+// ES Module build
+const esmConfig = {
+    ...baseConfig,
+    output: {
+        file: 'dist/sankey.esm.js',
+        format: 'es',
+        sourcemap: true,
+        inlineDynamicImports: true
+    }
+};
+
+// UMD build
+const umdConfig = {
+    ...baseConfig,
+    output: {
+        file: 'dist/sankey.umd.js',
+        format: 'umd',
+        name: 'energy-visualization-sankey',
+        globals: {
+            'd3': 'd3'
+        },
+        sourcemap: true,
+        inlineDynamicImports: true
+    }
+};
+
+// UMD minified build
+const umdMinConfig = {
+    ...baseConfig,
+    output: {
+        file: 'dist/sankey.umd.min.js',
+        format: 'umd',
+        name: 'energy-visualization-sankey',
+        globals: {
+            'd3': 'd3'
+        },
+        sourcemap: true,
+        inlineDynamicImports: true
+    },
+    plugins: [
+        ...baseConfig.plugins,
+        terser()
+    ]
+};
+
+// Standalone builds (include D3)
+const standaloneBaseConfig = {
+    input: 'src/core/Sankey.ts',
+    external: [], // Include D3 in standalone builds
+    plugins: [
+        resolve({
+            browser: true,
+            preferBuiltins: false
+        }),
+        typescript({
+            tsconfig: './tsconfig.json',
+            declaration: false, // Only generate types once
+            clean: true,
+            abortOnError: false,
+            rollupCommonJSResolveHack: false,
+            typescript: ts
+        })
+    ]
+};
+
+const standaloneEsmConfig = {
+    ...standaloneBaseConfig,
+    output: {
+        file: 'dist/sankey.standalone.esm.js',
+        format: 'es',
+        sourcemap: true,
+        inlineDynamicImports: true
+    }
+};
+
+const standaloneUmdConfig = {
+    ...standaloneBaseConfig,
+    output: {
+        file: 'dist/sankey.standalone.umd.js',
+        format: 'umd',
+        name: 'energy-visualization-sankey',
+        sourcemap: true,
+        inlineDynamicImports: true
+    }
+};
+
+const standaloneMinConfig = {
+    ...standaloneBaseConfig,
+    output: {
+        file: 'dist/sankey.standalone.min.js',
+        format: 'umd',
+        name: 'energy-visualization-sankey',
+        sourcemap: true,
+        inlineDynamicImports: true
+    },
+    plugins: [
+        ...standaloneBaseConfig.plugins,
+        terser()
+    ]
+};
+
+// Export appropriate configs based on environment
+export default isDev
+    ? [esmConfig, umdConfig, standaloneEsmConfig, standaloneUmdConfig] // Include standalone versions for dev testing
+    : [esmConfig, umdConfig, umdMinConfig, standaloneEsmConfig, standaloneUmdConfig, standaloneMinConfig];

package/scripts/performance-validation-real.js

@@ -0,0 +1,411 @@
+/**
+ * Performance Validation Script for US Energy Sankey v5
+ * Measures performance with REAL data (1800-2021, 222 years)
+ * Tests initialization, animation, and memory usage
+ */
+
+import {chromium} from 'playwright';
+import fs from 'fs';
+import path from 'path';
+import {fileURLToPath} from 'url';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+
+class RealDataPerformanceValidator {
+    constructor() {
+        this.browser = null;
+        this.performanceDir = path.join(__dirname, '../validation/performance');
+        this.ensureDirectories();
+    }
+
+    ensureDirectories() {
+        if (!fs.existsSync(this.performanceDir)) {
+            fs.mkdirSync(this.performanceDir, {recursive: true});
+            console.log(`📁 Created performance directory: ${this.performanceDir}`);
+        }
+    }
+
+    async setup() {
+        console.log('⚡ Setting up browser for performance validation...');
+        this.browser = await chromium.launch({
+            headless: true,
+            args: [
+                '--no-sandbox',
+                '--disable-dev-shm-usage',
+                '--enable-precise-memory-info'
+            ]
+        });
+    }
+
+    async measureInitializationPerformance() {
+        const page = await this.browser.newPage();
+
+        try {
+            console.log('📊 Measuring initialization performance with 222 years of real data...');
+
+            // Navigate to the test page first
+            await page.goto('http://localhost:8080/examples/visual-test.html', {
+                waitUntil: 'networkidle',
+                timeout: 30000
+            });
+
+            const metrics = await page.evaluate(() => {
+                return new Promise((resolve) => {
+                    const overallStart = performance.now();
+
+                    // Wait for sankey to be available and initialized
+                    const checkForSankey = () => {
+                        if (window.sankey && window.sankey.isInitialized()) {
+                            const overallEnd = performance.now();
+                            const dataService = window.sankey.getDataService();
+
+                            resolve({
+                                totalTime: overallEnd - overallStart,
+                                dataPointCount: dataService.data.length,
+                                firstYear: dataService.firstYear,
+                                lastYear: dataService.lastYear,
+                                memoryUsage: performance.memory ? {
+                                    used: performance.memory.usedJSHeapSize,
+                                    total: performance.memory.totalJSHeapSize,
+                                    limit: performance.memory.jsHeapSizeLimit
+                                } : null,
+                                timestamp: new Date().toISOString()
+                            });
+                        } else {
+                            setTimeout(checkForSankey, 50);
+                        }
+                    };
+
+                    checkForSankey();
+                });
+            });
+
+            await page.close();
+            return metrics;
+
+        } catch (error) {
+            await page.close();
+            throw error;
+        }
+    }
+
+    async measureAnimationPerformance() {
+        const page = await this.browser.newPage();
+
+        try {
+            console.log('🎬 Measuring animation performance across historical periods...');
+
+            // Navigate to the page
+            await page.goto('http://localhost:8080/examples/visual-test.html', {
+                waitUntil: 'networkidle',
+                timeout: 30000
+            });
+
+            // Wait for sankey to initialize
+            await page.waitForFunction(() => {
+                return window.sankey && window.sankey.isInitialized() && window.sankey.getYears().length === 222;
+            }, {timeout: 20000});
+
+            const animationMetrics = await page.evaluate(() => {
+                return new Promise((resolve) => {
+                    const sankey = window.sankey;
+                    if (!sankey) {
+                        resolve({error: 'Sankey not available'});
+                        return;
+                    }
+
+                    // Test years representing major energy transitions
+                    const testYears = [1800, 1850, 1900, 1950, 1980, 2000, 2021];
+                    let currentYearIndex = 0;
+                    let frameCount = 0;
+                    let totalFrameTime = 0;
+                    const frameTimes = [];
+                    const yearTransitionTimes = [];
+
+                    const startTime = performance.now();
+
+                    const measureFrame = () => {
+                        const frameStart = performance.now();
+                        frameCount++;
+
+                        // Switch to next test year every 10 frames
+                        if (frameCount % 10 === 0 && currentYearIndex < testYears.length - 1) {
+                            currentYearIndex++;
+                            const transitionStart = performance.now();
+                            sankey.setYear(testYears[currentYearIndex]);
+                            const transitionEnd = performance.now();
+                            yearTransitionTimes.push(transitionEnd - transitionStart);
+                        }
+
+                        if (frameCount < 70) { // Test 70 frames across all years
+                            requestAnimationFrame(() => {
+                                const frameEnd = performance.now();
+                                const frameTime = frameEnd - frameStart;
+                                frameTimes.push(frameTime);
+                                totalFrameTime += frameTime;
+                                measureFrame();
+                            });
+                        } else {
+                            const endTime = performance.now();
+                            const totalDuration = endTime - startTime;
+
+                            resolve({
+                                totalDuration,
+                                frameCount,
+                                averageFrameTime: totalFrameTime / frameCount,
+                                averageFPS: (frameCount / totalDuration) * 1000,
+                                minFrameTime: Math.min(...frameTimes),
+                                maxFrameTime: Math.max(...frameTimes),
+                                yearTransitions: yearTransitionTimes.length,
+                                averageTransitionTime: yearTransitionTimes.reduce((a, b) => a + b, 0) / yearTransitionTimes.length,
+                                testedYears: testYears.slice(0, currentYearIndex + 1),
+                                memoryUsage: performance.memory ? {
+                                    used: performance.memory.usedJSHeapSize,
+                                    total: performance.memory.totalJSHeapSize
+                                } : null
+                            });
+                        }
+                    };
+
+                    measureFrame();
+                });
+            });
+
+            await page.close();
+            return animationMetrics;
+
+        } catch (error) {
+            await page.close();
+            throw error;
+        }
+    }
+
+    async measureMemoryUsage() {
+        const page = await this.browser.newPage();
+
+        try {
+            console.log('🧠 Measuring memory usage patterns...');
+
+            await page.goto('http://localhost:8080/examples/visual-test.html', {
+                waitUntil: 'networkidle',
+                timeout: 30000
+            });
+
+            await page.waitForFunction(() => {
+                return window.sankey && window.sankey.isInitialized();
+            }, {timeout: 20000});
+
+            const memoryMetrics = await page.evaluate(() => {
+                return new Promise((resolve) => {
+                    const sankey = window.sankey;
+                    const measurements = [];
+
+                    const takeMeasurement = (label) => {
+                        if (performance.memory) {
+                            measurements.push({
+                                label,
+                                used: performance.memory.usedJSHeapSize,
+                                total: performance.memory.totalJSHeapSize,
+                                timestamp: performance.now()
+                            });
+                        }
+                    };
+
+                    takeMeasurement('initial');
+
+                    // Force garbage collection if available
+                    if (window.gc) {
+                        window.gc();
+                    }
+
+                    takeMeasurement('after_gc');
+
+                    // Trigger heavy operations
+                    sankey.setYear(2021);
+                    takeMeasurement('after_year_change');
+
+                    sankey.play();
+                    setTimeout(() => {
+                        takeMeasurement('during_animation');
+                        sankey.pause();
+
+                        setTimeout(() => {
+                            takeMeasurement('after_pause');
+
+                            resolve({
+                                measurements,
+                                peakMemory: Math.max(...measurements.map(m => m.used)),
+                                memoryGrowth: measurements[measurements.length - 1].used - measurements[0].used
+                            });
+                        }, 1000);
+                    }, 2000);
+                });
+            });
+
+            await page.close();
+            return memoryMetrics;
+
+        } catch (error) {
+            await page.close();
+            throw error;
+        }
+    }
+
+    async runCompletePerformanceValidation() {
+        console.log('🚀 Starting comprehensive performance validation...\n');
+
+        const results = {};
+
+        try {
+            // Measure initialization performance
+            console.log('1/3 Testing initialization performance...');
+            results.initialization = await this.measureInitializationPerformance();
+            this.reportInitializationResults(results.initialization);
+
+            // Measure animation performance
+            console.log('\n2/3 Testing animation performance...');
+            results.animation = await this.measureAnimationPerformance();
+            this.reportAnimationResults(results.animation);
+
+            // Measure memory usage
+            console.log('\n3/3 Testing memory usage...');
+            results.memory = await this.measureMemoryUsage();
+            this.reportMemoryResults(results.memory);
+
+            // Save complete results
+            this.savePerformanceBaseline(results);
+
+            return results;
+
+        } catch (error) {
+            console.error('❌ Performance validation failed:', error);
+            throw error;
+        }
+    }
+
+    reportInitializationResults(metrics) {
+        if (metrics.error) {
+            console.error(`❌ Initialization error: ${metrics.error}`);
+            return;
+        }
+
+        console.log(`📊 Initialization Results:`);
+        console.log(`   Total time: ${metrics.totalTime.toFixed(2)}ms`);
+        console.log(`   Data points: ${metrics.dataPointCount} years (${metrics.firstYear}-${metrics.lastYear})`);
+
+        if (metrics.memoryUsage) {
+            console.log(`   Memory usage: ${(metrics.memoryUsage.used / 1024 / 1024).toFixed(2)}MB`);
+        }
+    }
+
+    reportAnimationResults(metrics) {
+        if (metrics.error) {
+            console.error(`❌ Animation error: ${metrics.error}`);
+            return;
+        }
+
+        console.log(`🎬 Animation Results:`);
+        console.log(`   Duration: ${metrics.totalDuration.toFixed(2)}ms`);
+        console.log(`   Frames: ${metrics.frameCount}`);
+        console.log(`   Average FPS: ${metrics.averageFPS.toFixed(2)}`);
+        console.log(`   Avg frame time: ${metrics.averageFrameTime.toFixed(2)}ms`);
+        console.log(`   Frame time range: ${metrics.minFrameTime.toFixed(2)}ms - ${metrics.maxFrameTime.toFixed(2)}ms`);
+        console.log(`   Year transitions: ${metrics.yearTransitions}`);
+        console.log(`   Avg transition time: ${metrics.averageTransitionTime.toFixed(2)}ms`);
+        console.log(`   Tested years: ${metrics.testedYears.join(', ')}`);
+    }
+
+    reportMemoryResults(metrics) {
+        console.log(`🧠 Memory Results:`);
+        console.log(`   Peak memory: ${(metrics.peakMemory / 1024 / 1024).toFixed(2)}MB`);
+        console.log(`   Memory growth: ${(metrics.memoryGrowth / 1024 / 1024).toFixed(2)}MB`);
+
+        console.log(`   Memory progression:`);
+        metrics.measurements.forEach(m => {
+            console.log(`     ${m.label}: ${(m.used / 1024 / 1024).toFixed(2)}MB`);
+        });
+    }
+
+    savePerformanceBaseline(results) {
+        const baselineFile = path.join(this.performanceDir, 'real-data-baseline.json');
+        const summaryFile = path.join(this.performanceDir, 'performance-summary.json');
+
+        // Save detailed results
+        fs.writeFileSync(baselineFile, JSON.stringify(results, null, 2));
+
+        // Save summary for easy comparison
+        const summary = {
+            timestamp: new Date().toISOString(),
+            dataPoints: results.initialization?.dataPointCount || 0,
+            initTime: results.initialization?.totalTime || 0,
+            avgFPS: results.animation?.averageFPS || 0,
+            peakMemoryMB: results.memory ? (results.memory.peakMemory / 1024 / 1024) : 0,
+            version: '5.0.0'
+        };
+
+        fs.writeFileSync(summaryFile, JSON.stringify(summary, null, 2));
+
+        console.log(`\n💾 Performance baseline saved:`);
+        console.log(`   Details: ${baselineFile}`);
+        console.log(`   Summary: ${summaryFile}`);
+    }
+
+    async teardown() {
+        if (this.browser) {
+            await this.browser.close();
+            console.log('🧹 Browser closed');
+        }
+    }
+}
+
+// Main execution
+async function main() {
+    const validator = new RealDataPerformanceValidator();
+
+    try {
+        await validator.setup();
+        const results = await validator.runCompletePerformanceValidation();
+
+        console.log('\n✅ Performance validation completed successfully!');
+
+        // Performance thresholds (adjust based on your requirements)
+        const thresholds = {
+            maxInitTime: 5000, // 5 seconds
+            minFPS: 30,
+            maxMemoryMB: 100
+        };
+
+        let failed = false;
+
+        if (results.initialization?.totalTime > thresholds.maxInitTime) {
+            console.error(`❌ Initialization too slow: ${results.initialization.totalTime.toFixed(2)}ms > ${thresholds.maxInitTime}ms`);
+            failed = true;
+        }
+
+        if (results.animation?.averageFPS < thresholds.minFPS) {
+            console.error(`❌ FPS too low: ${results.animation.averageFPS.toFixed(2)} < ${thresholds.minFPS}`);
+            failed = true;
+        }
+
+        if (results.memory?.peakMemory > thresholds.maxMemoryMB * 1024 * 1024) {
+            console.error(`❌ Memory usage too high: ${(results.memory.peakMemory / 1024 / 1024).toFixed(2)}MB > ${thresholds.maxMemoryMB}MB`);
+            failed = true;
+        }
+
+        if (failed) {
+            process.exit(1);
+        }
+
+    } catch (error) {
+        console.error('❌ Performance validation crashed:', error);
+        process.exit(1);
+    } finally {
+        await validator.teardown();
+    }
+}
+
+// Run if called directly
+if (import.meta.url === `file://${process.argv[1]}`) {
+    main();
+}