energy-visualization-sankey 1.0.0

package/src/styles/controls.css

@@ -0,0 +1,184 @@
+/* US Energy Sankey - Controls Styles */
+
+/* Range Slider */
+.range-slider {
+    width: 100%;
+    margin-top: 5px;
+    position: relative;
+    overflow: visible;
+    padding-top: 40px;
+}
+
+.range-slider__range {
+    -webkit-appearance: none;
+    width: 100%;
+    border-radius: 5px;
+    outline: none;
+    padding: 0;
+    margin: 0;
+}
+
+.range-slider__range:first-child {
+    background: #d7dcdf;
+}
+
+.range-slider__range::-webkit-slider-thumb {
+    -webkit-appearance: none;
+    appearance: none;
+    width: 11px;
+    height: 11px;
+    border-radius: 50%;
+    background: #fff;
+    box-shadow: 0 0 4px 0 rgba(0, 0, 0, 1);
+    cursor: pointer;
+    transition: background 0.15s ease-in-out;
+}
+
+.range-slider__range::-moz-range-thumb {
+    width: 11px;
+    height: 11px;
+    border: 0;
+    border-radius: 50%;
+    background: #fff;
+    box-shadow: 0 0 4px 0 rgba(0, 0, 0, 1);
+    cursor: pointer;
+    transition: background 0.15s ease-in-out;
+}
+
+/* Dynamic Year Display */
+#dynamicYear {
+    color: black;
+    position: absolute;
+    height: 25px;
+    width: 50px;
+    text-align: center;
+    border: 1px solid black;
+    border-radius: 3px;
+    display: block;
+    font-size: 16px;
+    top: 40%;
+    /*bottom: 100%;*/
+    background: white;
+    padding: 3px 5px;
+    box-shadow: 0 2px 4px rgba(0, 0, 0, 0.2);
+}
+
+/* Add downward arrow pointing to slider */
+#dynamicYear::after {
+    content: '';
+    position: absolute;
+    top: 100%;
+    left: 50%;
+    margin-left: -4px;
+    width: 0;
+    height: 0;
+    border-left: 4px solid transparent;
+    border-right: 4px solid transparent;
+    border-top: 6px solid black;
+}
+
+/* Play/Pause Button */
+#play-button {
+    border-radius: 0;
+    display: block;
+    height: 0;
+}
+
+#play-button:hover {
+    background: transparent !important;
+}
+
+#play-button.playbutton {
+    outline: 0;
+    background: transparent;
+    border-color: transparent transparent transparent #202020;
+    transition: 100ms all ease;
+    cursor: pointer;
+    border-style: solid;
+    border-width: 13px 0 13px 20px;
+}
+
+#play-button.playpaused {
+    outline: 0;
+    background: transparent;
+    height: 26px;
+    border-color: transparent transparent transparent #202020;
+    transition: 100ms all ease;
+    cursor: pointer;
+    border-style: double;
+    border-width: 0px 0 0px 20px;
+}
+
+#play-button.playbutton:hover {
+    border-color: transparent transparent transparent #404040;
+}
+
+/* Waste Heat Toggle Switch */
+.switch_box {
+    display: -webkit-box;
+    display: -ms-flexbox;
+    display: flex;
+    min-width: 200px;
+    -webkit-box-pack: center;
+    -ms-flex-pack: center;
+    justify-content: center;
+    -webkit-box-align: center;
+    -ms-flex-align: center;
+    align-items: center;
+    -webkit-box-flex: 1;
+    -ms-flex: 1;
+    flex: 1;
+}
+
+.box_1 {
+    background: #ffffff;
+}
+
+input[type="checkbox"].switch_1 {
+    -webkit-appearance: none;
+    -moz-appearance: none;
+    appearance: none;
+    width: 3.5em;
+    height: 1.5em;
+    background: black;
+    border-radius: 3em;
+    position: relative;
+    cursor: pointer;
+    outline: none;
+    -webkit-transition: all .2s ease-in-out;
+    transition: all .2s ease-in-out;
+}
+
+input[type="checkbox"].switch_1:checked {
+    background: black;
+}
+
+input[type="checkbox"].switch_1:after {
+    position: absolute;
+    content: "";
+    width: 1.5em;
+    height: 1.5em;
+    border-radius: 50%;
+    background: #fff;
+    -webkit-box-shadow: 0 0 .25em rgba(0, 0, 0, .3);
+    box-shadow: 0 0 .25em rgba(0, 0, 0, .3);
+    -webkit-transform: scale(.7);
+    transform: scale(.7);
+    left: 0;
+    -webkit-transition: all .2s ease-in-out;
+    transition: all .2s ease-in-out;
+}
+
+input[type="checkbox"].switch_1:checked:after {
+    left: calc(100% - 1.5em);
+}
+
+/* Milestone Tick Markers */
+#testTick .tick text {
+    cursor: pointer;
+}
+
+#testTick .tick text:hover {
+    color: grey;
+    transition: color 250ms;
+}

package/src/styles/sankey.css

@@ -0,0 +1,211 @@
+/* US Energy Sankey - Core Styles */
+
+/* Typography */
+text, tspan {
+    font-family: Fieldwork, Futura, sans-serif;
+    font-size: 16px;
+}
+
+/* Flow Styles */
+.flow {
+    fill: none;
+}
+
+.flow.heat {
+    stroke: #98002e;
+}
+
+.flow.elec, .flow.waste.heat {
+    stroke: #e49942;
+}
+
+.flow.waste {
+    stroke: #e49942;
+    opacity: 0.4;
+}
+
+.flow.solar {
+    stroke: #fed530;
+}
+
+.flow.nuclear {
+    stroke: #ca0813;
+}
+
+.flow.hydro {
+    stroke: #0b24fb;
+}
+
+.flow.wind {
+    stroke: #901d8f;
+}
+
+.flow.geo {
+    stroke: #905a1c;
+}
+
+.flow.gas {
+    stroke: #4cabf2;
+}
+
+.flow.coal {
+    stroke: #000000;
+}
+
+.flow.bio {
+    stroke: #46be48;
+}
+
+.flow.petro {
+    stroke: #095f0b;
+}
+
+/* Box Styles */
+.box.sector {
+    fill: #cccccc;
+}
+
+.box.solar {
+    fill: #fed530;
+}
+
+.box.nuclear {
+    fill: #ca0813;
+}
+
+.box.hydro {
+    fill: #0b24fb;
+}
+
+.box.wind {
+    fill: #901d8f;
+}
+
+.box.geo {
+    fill: #905a1c;
+}
+
+.box.gas {
+    fill: #4cabf2;
+}
+
+.box.coal {
+    fill: #000000;
+}
+
+.box.bio {
+    fill: #46be48;
+}
+
+.box.petro {
+    fill: #095f0b;
+}
+
+/* Other Elements */
+.maxline {
+    stroke: #cccccc;
+    stroke-width: 1px;
+}
+
+.bkgd {
+    fill: #000000;
+}
+
+/* Title Container */
+.title_container {
+    border-top: 2px solid #000000;
+    border-bottom: 1px solid #000000;
+    position: relative;
+}
+
+.title_container img {
+    max-height: 40px;
+    position: absolute;
+    top: 5px;
+}
+
+.title_container svg {
+    position: absolute;
+    font-size: 15px;
+}
+
+.title_container .title {
+    font-size: 1em;
+    fill: black;
+}
+
+.title_container .title .unit {
+    font-size: .9em;
+    font-weight: bold;
+}
+
+.title_container .title .year {
+    font-size: 3.1em;
+    font-weight: bold;
+    clear: left;
+    letter-spacing: .05em;
+    font-variant-numeric: tabular-nums;
+}
+
+.title_container .citation, .title_container .affiliation {
+    font-family: Fieldwork-HumThin, Futura, sans-serif;
+    font-size: 1em;
+    fill: #000000;
+    font-weight: bolder;
+}
+
+.title_container .title-bottom, .title_container .affiliation-bottom {
+    font-family: Fieldwork-HumThin, Futura, sans-serif;
+    font-size: 1em;
+    fill: #000000;
+    font-weight: bolder;
+}
+
+/* Totals */
+.total.sector {
+    font-size: 0.7em;
+    font-weight: bold;
+}
+
+.total.waste-level {
+    fill: #e49942;
+    opacity: 0.4;
+}
+
+/* Visibility */
+.hidden {
+    visibility: hidden;
+}
+
+/* Tooltip */
+.tooltip {
+    color: #000000;
+    position: absolute;
+    text-align: justify;
+    width: auto;
+    padding: 5px;
+    background: #efefef;
+    border: 1px solid black;
+    pointer-events: none;
+    z-index: 3;
+}
+
+.fuel_value {
+    text-align: center;
+    vertical-align: middle;
+}
+
+/* Waste Heat Visibility Control */
+.waste-heat-hidden .flow.waste {
+    display: none !important;
+}
+
+.waste-heat-hidden .total.waste-level {
+    display: none !important;
+}
+
+/* Smooth transition for waste heat toggle (optional) */
+.flow.waste,
+.total.waste-level {
+    transition: opacity 0.3s ease;
+}

package/src/types/index.ts

@@ -0,0 +1,220 @@
+/**
+ * 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
+ *
+ */
+
+// Error types
+export class SankeyError extends Error {
+    constructor(message: string, public code?: string) {
+        super(message);
+        this.name = 'SankeyError';
+    }
+}
+
+export class DataValidationError extends SankeyError {
+    constructor(message: string, public field?: string) {
+        super(message, 'DATA_VALIDATION');
+        this.name = 'DataValidationError';
+    }
+}
+
+// Energy sector breakdown interface
+export interface EnergySectorBreakdown {
+    readonly elec: number;
+    readonly res: number;
+    readonly ag: number;
+    readonly indus: number;
+    readonly trans: number;
+    readonly heat: number;
+
+    [key: string]: number; // Allow dynamic access
+}
+
+// Core data structures
+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;
+}
+
+// Options interface
+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> {
+    // All optional properties are now required with defaults
+}
+
+// Mathematical structures
+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,                                    // Electricity and residential
+    ag: number,
+    indus: number,
+    trans: number,
+    heat?: number | undefined,
+}
+
+export interface Offest {
+    x: OffestX;
+    y: OffestY;
+}
+
+// Summary data structures
+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;
+}
+
+// D3 Selection types
+export type D3SVGSelection = d3.Selection<SVGSVGElement, unknown, HTMLElement, any>;
+export type D3DivSelection = d3.Selection<HTMLDivElement, unknown, HTMLElement, any>;

package/src/utils/Logger.ts

@@ -0,0 +1,105 @@
+/**
+ * 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 class Logger {
+
+    constructor(private 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
+     */
+    public log(message: string, ...args: any[]): void {
+        if (this.options.debugLogging) {
+            console.log(message, ...args);
+        }
+    }
+
+    /**
+     * 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
+     */
+    public debug(message: string, ...args: any[]): void {
+        if (this.options.debugLogging) {
+            console.debug(message, ...args);
+        }
+    }
+
+    /**
+     * 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
+     */
+    public warn(message: string, ...args: any[]): void {
+        if (this.options.debugLogging) {
+            console.warn(message, ...args);
+        }
+    }
+}