add Range.clampDelta(), phetsims/center-and-variability#605

js/Range.ts

@@ -291,6 +291,14 @@ class Range implements TRange {
     };
   }
 
+  // Given a value and a delta to change that value, clamp the delta to make sure the value stays within range.
+  public clampDelta( value: number, delta: number ): number {
+    assert && assert( this.contains( value ) );
+    return value + delta < this.min ? this.min - value :
+           value + delta > this.max ? this.max - value :
+           delta;
+  }
+
   public static fromStateObject( stateObject: RangeStateObject ): Range {
     // eslint-disable-next-line no-html-constructors
     return new Range(

js/RangeTests.ts

@@ -93,4 +93,16 @@ QUnit.test( 'expandNormalizedValue', assert => {
   assert.ok( range.expandNormalizedValue( 2 ) === 18, 'double' );
   assert.ok( range.expandNormalizedValue( 0.5 ) === 6, 'half' );
   assert.ok( range.expandNormalizedValue( 0.75 ) === 8, 'random weird number' );
+} );
+
+QUnit.test( 'clampDelta', assert => {
+  assert.equal( new Range( 0, 20 ).clampDelta( 10, 21 ), 10, 'clamped1' );
+  assert.equal( new Range( 0, 20 ).clampDelta( 10, -21 ), -10, 'clamped2' );
+  assert.equal( new Range( 0, 20 ).clampDelta( 10, 2 ), 2, 'clamped2' );
+  assert.equal( new Range( 0, 1 ).clampDelta( 0, 2 ), 1, 'clamped2' );
+  assert.equal( new Range( 0, 1 ).clampDelta( 0, -2 ), 0, 'clamped2' );
+  assert.equal( new Range( 0, 1 ).clampDelta( 0, -0 ), 0, 'clamped2' );
+  assert.equal( new Range( 0, 1 ).clampDelta( 1, -0 ), 0, 'clamped2' );
+  assert.equal( new Range( 0, 1 ).clampDelta( 1, 10 ), 0, 'clamped2' );
+  assert.equal( new Range( 0, 1 ).clampDelta( 0.5, 10 ), 0.5, 'clamped2' );
 } );