This switches over to using proper matrix decomposition for interpolating between two CGAffineTransforms.

This follows the same approach as WebKit's implementation of TransformationMatrix (see the decompose2 function). By fully decomposing the matrices this way, we are better able to interpolate transforms that don't follow the RST format.

This also significantly improves the performance of interpolating CGAffineTransforms. The base case (identity transform) measured 67% better, and the complex case (RST transform) measured 64% better.

Best to review by commit:

• Add performance tests for CGAffineTransform interpolation. Note that these aren't run on CI (for various reasons) but help to check changes during development and with debugging performance issues.
• Move CGAffineTransform conformance to AnimatableProperty to a separate file. No functional changes here.
• Add snapshot tests for CGAffineTransform interpolation. These initial snapshot tests show where the old solution broke down.
• Use matrix decomposition for CGAffineTransform interpolation.

This adds conformance for CATransform3D to AnimatableProperty by decomposing the two matrices into their respective components, interpolating the values in the decomposed transforms, then recomposing the interpolated value into a CATransform3D. This follows the same pattern we use to interpolate CGAffineTransform.

Resolves #19.

Currently there isn't a great way to animate a collection of subelements.

For example, say your element has a property containing an array of subviews that should each be animated. If the count is known during construction, you can add each one by key path, but you lose the compiler safety by using indices in the key path. The other option here is to use an AnimationGroup, which brings back the compiler safety but loses the separation of construction and execution.

In order to support building animations of collections for which the number of elements isn't known during construction, we need a new type of content that can be added to the Animation.

• 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.

Resolves #43.

Stagehand separates the animation process into two phases: construction and execution. The construction phase consists of building up an Animation. The execution phase begins with a call to Animation.perform(...), optionally followed by calls to the returned AnimationInstance to control the animation.

Setting the animation's duration and repeat style are currently considered to be part of the construction phase and are controlled by the Animation.duration and Animation.repeatStyle properties, respectively.

This has some interesting characteristics when it comes to composing animations. An animation's duration and repeat style is effectively meaningless when it's added as a child to another animation. This can cause some confusion, since consumers may expect the parent animation to take its children's values into account.

This also affects the reusability of common animation components, even if they aren't being used as part of a larger animation. For example, consumers could define an animation factory that vends a common fadeOutAnimation that is used whenever they need to fade a view out. It is quite likely that the same duration and repeat style should not be used for all instances of a reusable animation across the app, so each use case may need to set these properties before executing the animation.

// Most construction happens in the factory.
var animation = AnimationFactory.fadeOut

// Do some final construction to get it ready.
animation.duration = 5
animation.repeatStyle = .repeating(count: 2, autoreversing: true)

// Execute the animation.
animation.perform(on: view)

Note that this code snippet could be cleaned up by injecting the duration and repeat style into the factory; however, this has the same root issue in that these values are being defined by the code responsible for the execution of a particular instance of this animation, rather than the construction of the common animation.

To solve this, we can move the source of truth for an animation's duration and repeat style to the execution phase. Specifically, we can add duration and repeatStyle parameters to the Animation.perform(...) method.

// Construction happens in the factory.
let animation = AnimationFactory.fadeOut

// Execute the animation with the desired duration and repeat style.
animation.perform(
    on: view,
    duration: 5,
    repeatStyle: .repeating(count: 2, autoreversing: true)
)

A similar change would also be made to the AnimationQueue.enqueue(...) method for that execution path.

animationQueue.enqueue(
    animation: animation,
    duration: 5,
    repeatStyle: .repeating(count: 2, autoreversing: true)
)

There are also cases, however, where consumers want to promote consistency in usage of a given animation. This is currently well-supported by the duration and repeatStyle properties on Animation. To continue supporting this use case, instead of removing these properties, we can rename them to defaultDuration and defaultRepeatStyle. The duration and repeatStyle parameters of the Animation.perform(...) method will then be made optional, where a value of nil indicates that the animation's default should be used.

// Construct the animation with a default duration and repeat style.
animation.defaultDuration = 5
animation.defaultRepeatStyle = .none

// Execute the animation using the default duration and repeat style.
animation.perform(on: view)

// Execute the animation with a duration of 2 and the default repeat style.
animation.perform(on: view, duration: 2)

The same changes will be reflected on AnimationGroup as well: updating the current AnimationGroup.duration and AnimationGroup.repeatStyle properties to the equivalent default-prefixed versions and adding duration and repeatStyle parameters to the AnimationGroup.perform(...) method.

Alternatives

This would be a breaking change in the framework. Alternatively, we could leave the Animation.duration and Animation.repeatStyle properties as-is, while still introducing the parameters in Animation.perform(...) to allow overriding the values in the execution phase. This would not be a breaking change, since unchanged code would use the default values. I think the breaking version of this is better for the framework in the long term, however, since using the default-prefixed property names makes it clearer that these do not represent the source of truth for the duration of the final animation instance.

Related Changes

Alongside this change, we may also want to update AnimationRepeatStyle.none to .noRepeat. This avoids a warning that appears when using .none with an optional AnimationRepeatStyle:

Assuming you mean 'Optional<AnimationRepeatStyle>.none'; did you mean 'AnimationRepeatStyle.none' instead?

This feature was never included in the public API and still had a lot of work left in order to get it working properly (in particular around interacting with other animation content). No progress has been made on this feature in the last 9 months and AFAIK there is no work planned for this in the near future.

This removes it from the framework for now to simplify things.

When building the demo app with the Xcode 12 GM, the compiler has trouble resolving the type of expressions:

Example/Stagehand/CollectionKeyframesViewController.swift:93:27: The compiler is unable to type-check this expression in reasonable time; try breaking up the expression into distinct sub-expressions
Example/Stagehand/CollectionKeyframesViewController.swift:99:27: The compiler is unable to type-check this expression in reasonable time; try breaking up the expression into distinct sub-expressions
Example/Unit Tests/CGAffineTransformInterpolationSnapshotTests.swift:59:9: Type of expression is ambiguous without more context

Previously, we were creating an array of decomposition candidates and finding the one with the shortest distance. This changes over to modifying the decomposed transform as necessarily using some simpler logic, similar to how WebKit approaches this (see blend2).

This change resulted in a 48% faster identity-to-identity interpolation and a 44% faster complex-to-complex interpolation.

By commit:

• Use quadrant view for CGAffineTransform interpolation snapshot tests. This makes it way easier to tell what's going on in a few of the trickier cases.
• Improve performance of CGAffineTransform interpolation.

This moves us to a combination of GitHub Actions and Travis CI for our CI builds. This separation prefers GitHub Actions when available, since it has some advantages (more concurrent builds, artifact upload, etc.), but falls back to Travis CI for iOS versions that aren't easily supported with GitHub Actions.

This adds a SnapshotTestCase class that other snapshot test classes can inherit from to get common behavior. In particular, this helps to ensure we use the same file name options across the project. This also adds enforcement that we're running on the set of devices for which we have snapshots.

This adds snapshot tests for a handful of animation curves, with snapshots that show the curve drawn on a grid.

The code to draw the grid is broken out into a separate utility shared with the sample app.

It's often useful to know whether an AnimationQueue is currently performing an animation. We should be able to add a hasInProgressAnimation property to AnimationQueue that looks at the queue and checks whether (1) there are any animations in the queue, and if so (2) whether the first animation is still active (i.e. not complete or cancelled).

We should be more consistent with the terminology we use in the project - both in the long form documentation and headerdocs, as well as some of the (private) variable names. For example, when talking about durations, the "duration" can apply to different parts of the animation, so I've started differentiating by saying:

• The time from the start of the execution phase to when the animation completes is the end-to-end duration. This is usually a calculated value based on the cycle duration and the repeat style (when available).
• The time for the animation to go from a relative timestamp of 0 to 1 (or 1 to 0) is the cycle duration. This is typically how consumers specify the duration.
• The time for the animation to go between two arbitrary relative timestamps is the segment duration. This is used in a few places like snapshot testing and the upcoming interactive animations.

See original suggestion in https://github.com/cashapp/stagehand/pull/49#r499112281

This adds support for interactive animations.

Very much still a draft a this point. The exact requirements are still TBD (see #34). This is a proposal for one potential API, to give us something to play around with and see if it works well.

Adding support for interactive animations will greatly increase the variety of use cases where Stagehand can be applied.

The exact requirements for what this feature should support is still an open question. At this point we're collecting data on what use cases we want to support, so we can design the API around that.