From 1cc8831f9a34182185e44d031bfc756b3f90a05e Mon Sep 17 00:00:00 2001
From: pixelzoom <cmalley@pixelzoom.com>
Date: Mon, 15 Jul 2024 14:33:36 -0600
Subject: [PATCH] animate from current value of heatCoolAmountProperty, improve
 doc, https://github.com/phetsims/gas-properties/issues/283

(cherry picked from commit 97f65d111c7ef547a3cf5b21a930c1ea5d0b7565)
---
 .../view/GasPropertiesHeaterCoolerNode.ts     | 31 +++++++++++--------
 1 file changed, 18 insertions(+), 13 deletions(-)

diff --git a/js/common/view/GasPropertiesHeaterCoolerNode.ts b/js/common/view/GasPropertiesHeaterCoolerNode.ts
index 02e52b4a..3c0df1b6 100644
--- a/js/common/view/GasPropertiesHeaterCoolerNode.ts
+++ b/js/common/view/GasPropertiesHeaterCoolerNode.ts
@@ -102,8 +102,8 @@ export default class GasPropertiesHeaterCoolerNode extends HeaterCoolerNode {
             const deltaT = temperature - previousTemperature;
             if ( Math.abs( deltaT ) > MIN_DELTA_T ) {
               const deltaTN = deltaT * numberOfParticlesProperty.value;
-              const heatCoolFactor = Math.sign( deltaT ) * toHeatFactor.evaluate( Math.abs( deltaTN ) );
-              this.startAnimation( heatCoolFactor );
+              const heatCoolAmount = Math.sign( deltaT ) * toHeatFactor.evaluate( Math.abs( deltaTN ) );
+              this.doAnimation( heatCoolAmount );
             }
           }
         }
@@ -140,46 +140,51 @@ export default class GasPropertiesHeaterCoolerNode extends HeaterCoolerNode {
   }
 
   /**
-   * Starts the animation to a new heatCoolFactor value.
+   * Animates to a new heatCoolAmount value, followed by animation to zero.
    */
-  private startAnimation( heatCoolFactor: number ): void {
-    assert && assert( heatCoolFactor >= -1 && heatCoolFactor <= 1, `invalid heatCoolFactor: ${heatCoolFactor}` );
+  private doAnimation( heatCoolAmount: number ): void {
+    assert && assert( heatCoolAmount >= -1 && heatCoolAmount <= 1, `invalid heatCoolAmount: ${heatCoolAmount}` );
+
+    const currentHeatCoolAmount = this.heatCoolAmountProperty.value;
 
     this.stopAnimation();
 
-    // Animation that moves the flame/ice up
+    // Animate from currentHeatCoolAmount to heatCoolAmount.
     this.animation = new Animation( {
       property: this.heatCoolAmountProperty,
-      to: heatCoolFactor,
+      from: currentHeatCoolAmount,
+      to: heatCoolAmount,
       duration: HEAT_COOL_DURATION / 2,
       easing: Easing.CUBIC_OUT, // accelerates
       stepEmitter: STEP_EMITTER
     } );
 
-    // If the Animation is stopped prematurely, abruptly turn off heat/cool
+    // If the animation is stopped prematurely, go immediately to zero and clean up.
     this.animation.stopEmitter.addListener( () => {
-      this.animation = null;
       this.heatCoolAmountProperty.value = 0;
+      this.animation = null;
     } );
 
-    // When the 'up' Animation finishes...
+    // When animation to heatCoolAmount finishes, animate back to zero.
     this.animation.finishEmitter.addListener( () => {
 
-      // Animation that moves the flame/ice down
+      // Animate from heatCoolAmount to zero.
       this.animation = new Animation( {
         property: this.heatCoolAmountProperty,
+        from: heatCoolAmount,
         to: 0,
         duration: HEAT_COOL_DURATION / 2,
         easing: Easing.CUBIC_IN, // decelerates
         stepEmitter: STEP_EMITTER
       } );
 
-      // If the down animation is stopped, abruptly turn off heat/cool.
+      // If the animation is stopped prematurely, go immediately to zero and clean up.
       this.animation.stopEmitter.addListener( () => {
         this.heatCoolAmountProperty.value = 0;
+        this.animation = null;
       } );
 
-      // When the down Animation finishes, we're done.
+      // When the animation finishes, clean up.
       this.animation.finishEmitter.addListener( () => {
         this.animation = null;
       } );