Move source of truth for duration and repeat style to the execution p…

…hase (#49)

* Adds `duration` and `repeatStyle` parameters to the `Animation.perform(...)` and `AnimationQueue.enqueue(...)` methods to allow for specifying an explicit duration and repeat style at the start of the execution phase.
* Renames the `duration` properties on `Animation` and `AnimationGroup` to `implicitDuration`.
* Renames the `repeatStyle` properties on `Animation` and `AnimationGroup` to `implicitRepeatStyle`.
* Renames `AnimationRepeatStyle.none` to `.noRepeat` to avoid an ambiguous reference when using an optional repeat style.
* Updates a lot of headerdocs to better explain how the duration and repeat styles are resolved.

Example/Stagehand Tutorial.playground/Pages/Animation Groups.xcplaygroundpage/Contents.swift

@@ -24,7 +24,8 @@ animationGroup.addAnimation(secondAnimation, for: secondElement, startingAt: 0,
 
 /*:
 
- Like normal `Animation`s, we can change the `duration`, `curve`, and `repeatStyle` of our animation group as a whole.
+ Like normal `Animation`s, we can change the `implicitDuration`, `curve`, and `implicitRepeatStyle` of our animation
+ group as a whole.
 
  When we're ready to perform the animation, we call the `perform(delay:completion:)` method.
 

Example/Stagehand Tutorial.playground/Pages/Assigning Properties During Animations.xcplaygroundpage/Contents.swift

@@ -42,7 +42,7 @@ propertyAssignmentAnimation.addAssignment(for: \.clipsToBounds, at: 0.5, value:
 
  */
 
-propertyAssignmentAnimation.repeatStyle = .infinitlyRepeating(autoreversing: true)
+propertyAssignmentAnimation.implicitRepeatStyle = .infinitelyRepeating(autoreversing: true)
 
 let view = ExpandedBoundsView(frame: .init(x: 0, y: 0, width: 100, height: 100))
 PlaygroundPage.current.liveView = WrapperView(wrappedView: view)

Example/Stagehand Tutorial.playground/Pages/Composing Animations.xcplaygroundpage/Contents.swift

@@ -39,7 +39,7 @@ func makeFlatAnimation() -> Animation<RaceCarView> {
     animation.addKeyframe(for: \.bottomView.backgroundColor, at: 0.75, value: UIColor.yellow.withAlphaComponent(0.8))
     animation.addKeyframe(for: \.bottomView.backgroundColor, at: 1, value: .yellow)
 
-    animation.duration = 3
+    animation.implicitDuration = 3
 
     return animation
 }
@@ -94,7 +94,7 @@ func makeHierarchicalAnimation() -> Animation<RaceCarView> {
     animation.addChild(makeCarAnimation(), for: \.topView, startingAt: 0, relativeDuration: 1)
     animation.addChild(makeCarAnimation(), for: \.bottomView, startingAt: 0, relativeDuration: 1)
 
-    animation.duration = 3
+    animation.implicitDuration = 3
 
     return animation
 }

Example/Stagehand Tutorial.playground/Pages/Creating and Executing an Animation.xcplaygroundpage/Contents.swift

@@ -18,7 +18,7 @@ import Stagehand
 
 var basicAnimation = Animation<UIView>()
 
-basicAnimation.duration = 2
+basicAnimation.implicitDuration = 2
 
 /*:
 

Example/Stagehand Tutorial.playground/Pages/Executing Code During Animations.xcplaygroundpage/Contents.swift

@@ -95,7 +95,7 @@ func makeAnimation(model: ModelDrivenView.Model) -> Animation<ModelDrivenView> {
     animation.addKeyframe(for: \.alpha, at: 1, value: 1)
 
     // Make the total duration of the animation 2 seconds.
-    animation.duration = 2
+    animation.implicitDuration = 2
 
     return animation
 }
@@ -148,8 +148,8 @@ func makeAnimation(modelToFlash: ModelDrivenView.Model, modelToRestore: ModelDri
         at: 0.5
     )
 
-    animation.duration = 2
-    animation.repeatStyle = .repeating(count: 2, autoreversing: true)
+    animation.implicitDuration = 2
+    animation.implicitRepeatStyle = .repeating(count: 2, autoreversing: true)
 
     return animation
 }

Example/Stagehand Tutorial.playground/Pages/Executing Code Every Frame.xcplaygroundpage/Contents.swift

@@ -31,7 +31,7 @@ final class DisplayLinkAnimator {
 
     // MARK: - Private Properties
 
-    private let displayLink: CADisplayLink!
+    private var displayLink: CADisplayLink!
 
     private let startTime: CFTimeInterval
 

Example/Stagehand Tutorial.playground/Pages/Repeating Animations.xcplaygroundpage/Contents.swift

@@ -9,14 +9,14 @@ import Stagehand
  By default, animations will run once before completing. Sometimes, though, we want our animation to loop through
  multiple times, sometimes even indefinitely.
 
- Using the `Animation.repeatStyle` property, we can control how our animation repeats.
+ Using the `Animation.implicitRepeatStyle` property, we can control how our animation repeats.
 
  */
 
 var animation = Animation<UIView>()
 
 // The default style is to not repeat.
-animation.repeatStyle = .none
+animation.implicitRepeatStyle = .noRepeat
 
 /*:
 
@@ -25,7 +25,7 @@ animation.repeatStyle = .none
 
  */
 
-animation.repeatStyle = .repeating(count: 2, autoreversing: false)
+animation.implicitRepeatStyle = .repeating(count: 2, autoreversing: false)
 
 /*:
 
@@ -34,7 +34,7 @@ animation.repeatStyle = .repeating(count: 2, autoreversing: false)
 
  */
 
-animation.repeatStyle = .infinitelyRepeating(autoreversing: false)
+animation.implicitRepeatStyle = .infinitelyRepeating(autoreversing: false)
 
 /*:
 

Example/Stagehand/AnimationCancelationViewController.swift

@@ -32,7 +32,7 @@ final class AnimationCancelationViewController: DemoViewController {
                 self.animationInstance?.cancel()
 
                 let animation = self.makeAnimation()
-                self.animationInstance = animation.perform(on: self.mainView.animatableView)
+                self.animationInstance = animation.perform(on: self.mainView.animatableView, duration: 2)
             }),
             ("Cancel (Revert)", { [unowned self] in
                 self.animationInstance?.cancel(behavior: .revert)
@@ -58,7 +58,6 @@ final class AnimationCancelationViewController: DemoViewController {
         var animation = Animation<UIView>()
         animation.addKeyframe(for: \.transform, at: 0, value: .identity)
         animation.addKeyframe(for: \.transform, at: 1, value: .init(translationX: mainView.bounds.width - 100, y: 0))
-        animation.duration = 2
         return animation
     }
 

Example/Stagehand/AnimationCurveViewController.swift

@@ -117,7 +117,7 @@ final class AnimationCurveViewController: DemoViewController {
         var animation = Animation<UIView>()
         animation.addKeyframe(for: \.transform, at: 0, value: .identity)
         animation.addKeyframe(for: \.transform, at: 1, value: .init(translationX: mainView.bounds.width - 100, y: 0))
-        animation.duration = 2
+        animation.implicitDuration = 2
 
         animation.addPerFrameExecution { [weak self] context in
             guard let self = self else { return }

Example/Stagehand/AnimationGroupViewController.swift

@@ -29,15 +29,14 @@ final class AnimationGroupViewController: DemoViewController {
         animationRows = [
             ("Move Both Views", { [unowned self] in
                 var animationGroup = AnimationGroup()
-                animationGroup.duration = 2
 
                 let topAnimation = self.makeAnimation()
                 animationGroup.addAnimation(topAnimation, for: self.topView, startingAt: 0, relativeDuration: 0.75)
 
                 let bottomAnimation = self.makeAnimation()
                 animationGroup.addAnimation(bottomAnimation, for: self.bottomView, startingAt: 0.25, relativeDuration: 0.75)
 
-                animationGroup.perform()
+                animationGroup.perform(duration: 2)
             }),
         ]
     }
@@ -54,7 +53,6 @@ final class AnimationGroupViewController: DemoViewController {
         var animation = Animation<UIView>()
         animation.addKeyframe(for: \.transform, at: 0, value: .identity)
         animation.addKeyframe(for: \.transform, at: 1, value: .init(translationX: contentView.bounds.width - 100, y: 0))
-        animation.duration = 2
         return animation
     }
 

Example/Stagehand/AnimationQueueViewController.swift

@@ -66,7 +66,7 @@ final class AnimationQueueViewController: DemoViewController {
 
     private func makeTranslationAnimation(x: CGFloat, y: CGFloat) -> Animation<View> {
         var animation = Animation<View>()
-        animation.duration = 2
+        animation.implicitDuration = 2
 
         animation.addKeyframe(for: \.animatableView.transform, at: 0, relativeValue: { $0 })
         animation.addKeyframe(for: \.animatableView.transform, at: 1, value: .init(translationX: x, y: y))

Example/Stagehand/ChildAnimationProgressViewController.swift

@@ -246,7 +246,7 @@ final class ChildAnimationProgressViewController: DemoViewController {
 
         parentAnimation.addChild(childAnimation, for: \.self, startingAt: 0.25, relativeDuration: 0.5)
 
-        parentAnimation.duration = 4
+        parentAnimation.implicitDuration = 4
         return parentAnimation
     }
 

Example/Stagehand/ChildAnimationsViewController.swift

@@ -119,9 +119,7 @@ final class ChildAnimationsViewController: DemoViewController {
                 animation.addChild(fadeOutAnimation, for: \.self, startingAt: 0, relativeDuration: 0.5)
                 animation.addChild(fadeInAnimation, for: \.self, startingAt: 0.5, relativeDuration: 0.5)
 
-                animation.duration = 2
-
-                animation.perform(on: self.mainView)
+                animation.perform(on: self.mainView, duration: 2)
             }),
         ]
     }

Example/Stagehand/ChildAnimationsWithCurvesViewController.swift

@@ -33,7 +33,6 @@ final class ChildAnimationsWithCurvesViewController: DemoViewController {
             }),
             ("Linear / Ease In Ease Out", { [unowned self] in
                 var animation = Animation<View>()
-                animation.duration = 2
 
                 var topAnimation = self.makeAnimation()
                 topAnimation.curve = LinearAnimationCurve()
@@ -43,7 +42,7 @@ final class ChildAnimationsWithCurvesViewController: DemoViewController {
                 bottomAnimation.curve = SinusoidalEaseInEaseOutAnimationCurve()
                 animation.addChild(bottomAnimation, for: \View.bottomView, startingAt: 0, relativeDuration: 1)
 
-                animation.perform(on: self.mainView)
+                animation.perform(on: self.mainView, duration: 2)
             }),
         ]
     }
@@ -58,7 +57,6 @@ final class ChildAnimationsWithCurvesViewController: DemoViewController {
         var animation = Animation<UIView>()
         animation.addKeyframe(for: \.transform, at: 0, value: .identity)
         animation.addKeyframe(for: \.transform, at: 1, value: .init(translationX: mainView.bounds.width - 100, y: 0))
-        animation.duration = 2
         return animation
     }
 

Example/Stagehand/ColorAnimationsViewController.swift

@@ -40,69 +40,63 @@ final class ColorAnimationsViewController: DemoViewController {
                 self.animationInstance?.cancel()
 
                 var animation = Animation<UIView>()
-                animation.duration = 2
 
                 animation.addKeyframe(for: \.backgroundColor, at: 0, value: .red)
                 animation.addKeyframe(for: \.backgroundColor, at: 1, value: .green)
 
-                self.animationInstance = animation.perform(on: self.contentView)
+                self.animationInstance = animation.perform(on: self.contentView, duration: 2)
             }),
             ("Red (sRGB) -> nil -> Green (sRGB)", { [unowned self] in
                 self.animationInstance?.cancel()
 
                 var animation = Animation<UIView>()
-                animation.duration = 2
 
                 animation.addKeyframe(for: \.backgroundColor, at: 0, value: .red)
                 animation.addKeyframe(for: \.backgroundColor, at: 0.5, value: nil)
                 animation.addKeyframe(for: \.backgroundColor, at: 1, value: .green)
 
-                self.animationInstance = animation.perform(on: self.contentView)
+                self.animationInstance = animation.perform(on: self.contentView, duration: 2)
             }),
             ("Red (P3) -> Green (P3)", { [unowned self] in
                 self.animationInstance?.cancel()
 
                 var animation = Animation<UIView>()
-                animation.duration = 2
 
                 animation.addKeyframe(for: \UIView.backgroundColor, at: 0, value: UIColor(displayP3Red: 1, green: 0, blue: 0, alpha: 1))
                 animation.addKeyframe(for: \UIView.backgroundColor, at: 1, value: UIColor(displayP3Red: 0, green: 1, blue: 0, alpha: 1))
 
-                self.animationInstance = animation.perform(on: self.contentView)
+                self.animationInstance = animation.perform(on: self.contentView, duration: 2)
             }),
             ("Red (sRGB) -> Green (P3)", { [unowned self] in
                 self.animationInstance?.cancel()
 
                 var animation = Animation<UIView>()
-                animation.duration = 2
 
                 animation.addKeyframe(for: \UIView.backgroundColor, at: 0, value: .red)
                 animation.addKeyframe(for: \UIView.backgroundColor, at: 1, value: UIColor(displayP3Red: 0, green: 1, blue: 0, alpha: 1))
 
-                self.animationInstance = animation.perform(on: self.contentView)
+                self.animationInstance = animation.perform(on: self.contentView, duration: 2)
             }),
             ("Red (sRGB) -> Red (P3)", { [unowned self] in
                 self.animationInstance?.cancel()
 
                 var animation = Animation<UIView>()
-                animation.duration = 2
 
                 animation.addKeyframe(for: \UIView.backgroundColor, at: 0, value: .red)
                 animation.addKeyframe(for: \UIView.backgroundColor, at: 1, value: UIColor(displayP3Red: 1, green: 0, blue: 0, alpha: 1))
 
-                self.animationInstance = animation.perform(on: self.contentView)
+                self.animationInstance = animation.perform(on: self.contentView, duration: 2)
             }),
             ("Red (sRGB), with alpha 1 -> 0.5 -> 1", { [unowned self] in
                 self.animationInstance?.cancel()
 
                 var animation = Animation<UIView>()
-                animation.duration = 2
 
                 animation.addKeyframe(for: \UIView.backgroundColor, at: 0.0, value: UIColor.red)
                 animation.addKeyframe(for: \UIView.backgroundColor, at: 0.5, value: UIColor.red.withAlphaComponent(0.5))
                 animation.addKeyframe(for: \UIView.backgroundColor, at: 1.0, value: UIColor.red)
 
-                self.animationInstance = animation.perform(on: self.contentView)
+                self.animationInstance = animation.perform(on: self.contentView, duration: 2)
             }),
         ]
     }

Example/Stagehand/ExecutionBlockViewController.swift

@@ -66,10 +66,13 @@ final class ExecutionBlockViewController: DemoViewController {
                     },
                     at: 1
                 )
-                animation.repeatStyle = .repeating(count: 2, autoreversing: true)
 
                 feedbackGenerator.prepare()
-                self.animationInstance = animation.perform(on: self.mainView.animatableView)
+                self.animationInstance = animation.perform(
+                    on: self.mainView.animatableView,
+                    duration: 2,
+                    repeatStyle: .repeating(count: 2, autoreversing: true)
+                )
             }),
         ]
     }
@@ -86,7 +89,6 @@ final class ExecutionBlockViewController: DemoViewController {
         var animation = Animation<UIView>()
         animation.addKeyframe(for: \.transform, at: 0, value: .identity)
         animation.addKeyframe(for: \.transform, at: 1, value: .init(translationX: mainView.bounds.width - 100, y: 0))
-        animation.duration = 2
         return animation
     }
 

Example/Stagehand/PerformanceBenchmarkViewController.swift

@@ -41,8 +41,8 @@ final class PerformanceBenchmarkViewController: DemoViewController {
                 animation.addKeyframe(for: \.centerView.transform, at: 0.75, value: .init(rotationAngle: .pi * 3 / 2))
                 animation.addKeyframe(for: \.centerView.transform, at: 1.00, value: .identity)
 
-                animation.duration = 4
-                animation.repeatStyle = .infinitelyRepeating(autoreversing: true)
+                animation.implicitDuration = 4
+                animation.implicitRepeatStyle = .infinitelyRepeating(autoreversing: true)
 
                 self.animationInstances.append(animation.perform(on: self.mainView))
             }),
@@ -68,8 +68,8 @@ final class PerformanceBenchmarkViewController: DemoViewController {
                     )
                 }
 
-                animation.duration = 3.5
-                animation.repeatStyle = .infinitelyRepeating(autoreversing: false)
+                animation.implicitDuration = 3.5
+                animation.implicitRepeatStyle = .infinitelyRepeating(autoreversing: false)
 
                 self.animationInstances.append(animation.perform(on: self.mainView))
             }),

Example/Stagehand/PropertyAssignmentViewController.swift

@@ -50,19 +50,18 @@ final class PropertyAssignmentViewController: DemoViewController {
 
                 var animation = Animation<View>()
                 animation.addChild(childAnimation, for: \.animatableView, startingAt: 0, relativeDuration: 1)
-                animation.duration = 2
 
-                self.animationInstance = animation.perform(on: self.mainView)
+                self.animationInstance = animation.perform(on: self.mainView, duration: 2)
             }),
             ("Current -> Yellow -> Green, with reversal", { [unowned self] in
                 var animation = self.makeAnimation()
                 animation.addAssignment(for: \.backgroundColor, at: 0.33, value: .yellow)
                 animation.addAssignment(for: \.backgroundColor, at: 0.66, value: .green)
-                animation.repeatStyle = .repeating(count: 2, autoreversing: true)
 
                 self.mainView.initialColorSlider.isEnabled = false
                 self.animationInstance = animation.perform(
                     on: self.mainView.animatableView,
+                    repeatStyle: .repeating(count: 2, autoreversing: true),
                     completion: { [weak self] _ in
                         self?.mainView.initialColorSlider.isEnabled = true
                 }
@@ -85,7 +84,7 @@ final class PropertyAssignmentViewController: DemoViewController {
         var animation = Animation<UIView>()
         animation.addKeyframe(for: \.transform, at: 0, value: .identity)
         animation.addKeyframe(for: \.transform, at: 1, value: .init(translationX: mainView.bounds.width - 100, y: 0))
-        animation.duration = 2
+        animation.implicitDuration = 2
         return animation
     }