[breaking] Use the keyPath as the key when the animator is not additive. (#22)

* [breaking] Use the keyPath as the key when the animator is not additive.

When the animator is not additive we don't actually want our animations to stack on top of one another.

There are some scenarios where stacking absolute animations is desired, e.g. creating a "keyframe" animation composed of a variety of beginTime-adjusted animations, but in practice this is the exception rather than the norm. As such, the API is being adjusted to use the keyPath as the animation key when the animator is not additive.

* More docs.

* Method name.

Author: jverkoey

src/MDMMotionAnimator.h

@@ -66,6 +66,10 @@ NS_SWIFT_NAME(MotionAnimator)
 /**
  Adds a single animation to the layer with the given timing structure.
 
+ If `additive` is disabled, the animation will be added to the layer with the keyPath as its key.
+ In this case, multiple invocations of this function on the same key path will remove the
+ animations added from prior invocations.
+
  @param timing The timing to be used for the animation.
  @param layer The layer to be animated.
  @param values The values to be used in the animation. Must contain exactly two values. Supported
@@ -81,6 +85,10 @@ NS_SWIFT_NAME(MotionAnimator)
 /**
  Adds a single animation to the layer with the given timing structure.
 
+ If `additive` is disabled, the animation will be added to the layer with the keyPath as its key.
+ In this case, multiple invocations of this function on the same key path will remove the
+ animations added from prior invocations.
+
  @param timing The timing to be used for the animation.
  @param layer The layer to be animated.
  @param values The values to be used in the animation. Must contain exactly two values. Supported

src/MDMMotionAnimator.m

@@ -100,7 +100,8 @@ - (void)animateWithTiming:(MDMMotionTiming)timing
 
       // When we use a nil key, Core Animation will ensure that the animation is added with a
       // unique key - this enables our additive animations to stack upon one another.
-      [layer addAnimation:animation forKey:nil];
+      NSString *key = _additive ? nil : keyPath;
+      [layer addAnimation:animation forKey:key];
 
       for (void (^tracer)(CALayer *, CAAnimation *) in _tracers) {
         tracer(layer, animation);

tests/unit/MotionAnimatorTests.swift

@@ -47,8 +47,10 @@ class MotionAnimatorTests: XCTestCase {
     XCTAssertTrue(true)
   }
 
-  func testAnimatorOnlyAddsAnimationsForKeyPath() {
+  func testAnimatorOnlyUsesSingleNonAdditiveAnimationForKeyPath() {
     let animator = MotionAnimator()
+    animator.additive = false
+
     let timing = MotionTiming(delay: 0,
                               duration: 1,
                               curve: .init(type: .bezier, data: (0, 0, 0, 0)),
@@ -64,9 +66,7 @@ class MotionAnimatorTests: XCTestCase {
     UIView.animate(withDuration: 0.5) {
       animator.animate(with: timing, to: view.layer, withValues: [0, 1], keyPath: .rotation)
 
-      // Setting transform.rotation.z will create an implicit transform if implicit animations
-      // aren't disabled by the animator properly, so verify that such an animation doesn't exist:
-      XCTAssertNil(view.layer.animation(forKey: "transform"))
+      XCTAssertEqual(view.layer.animationKeys()?.count, 1)
     }
   }
 }