lottie-ios 3.2.0 → 3.4.0

package/README.md

@@ -1,18 +1,17 @@
-# Lottie for iOS, macOS (and [Android](https://github.com/airbnb/lottie-android) and [React Native](https://github.com/airbnb/lottie-react-native))
-[![Version](https://img.shields.io/cocoapods/v/lottie-ios.svg?style=flat)](https://cocoapods.org/pods/lottie-ios)[![License](https://img.shields.io/cocoapods/l/lottie-ios.svg?style=flat)](https://cocoapods.org/pods/lottie-ios)[![Platform](https://img.shields.io/cocoapods/p/lottie-ios.svg?style=flat)](https://cocoapods.org/pods/lottie-ios)
+# Lottie for iOS
+ [![Version](https://img.shields.io/cocoapods/v/lottie-ios.svg?style=flat)](https://cocoapods.org/pods/lottie-ios) [![License](https://img.shields.io/cocoapods/l/lottie-ios.svg?style=flat)](https://cocoapods.org/pods/lottie-ios) [![Platform](https://img.shields.io/endpoint?url=https%3A%2F%2Fswiftpackageindex.com%2Fapi%2Fpackages%2Fairbnb%2Flottie-ios%2Fbadge%3Ftype%3Dplatforms)](https://swiftpackageindex.com/airbnb/lottie-ios) [![Swift Versions](https://img.shields.io/endpoint?url=https%3A%2F%2Fswiftpackageindex.com%2Fapi%2Fpackages%2Fairbnb%2Flottie-ios%2Fbadge%3Ftype%3Dswift-versions)](https://swiftpackageindex.com/airbnb/lottie-ios)
 
-# View documentation, FAQ, help, examples, and more at [airbnb.io/lottie](http://airbnb.io/lottie/)
+**View documentation, FAQ, help, examples, and more at [airbnb.io/lottie](http://airbnb.io/lottie/)**
 
-Lottie is a mobile library for Android and iOS that natively renders vector based animations and art in realtime with minimal code.
+Lottie is a cross-platform library for iOS, macOS, tvOS, [Android](https://github.com/airbnb/lottie), and [Web](https://github.com/airbnb/lottie-web) that natively renders vector based animations and art in realtime with minimal code.
 
-Lottie loads and renders animations and vectors exported in the bodymovin JSON format. Bodymovin JSON can be created and exported from After Effects with [bodymovin](https://github.com/bodymovin/bodymovin), Sketch with [Lottie Sketch Export](https://github.com/buba447/Lottie-Sketch-Export), and from [Haiku](https://www.haiku.ai). 
+Lottie loads and renders animations and vectors exported in the bodymovin JSON format. Bodymovin JSON can be created and exported from After Effects with [bodymovin](https://github.com/bodymovin/bodymovin), Sketch with [Lottie Sketch Export](https://github.com/buba447/Lottie-Sketch-Export), and from [Haiku](https://www.haiku.ai).
 
-For the first time, designers can create **and ship** beautiful animations without an engineer painstakingly recreating it by hand.
+Designers can create **and ship** beautiful animations without an engineer painstakingly recreating it by hand.
 Since the animation is backed by JSON they are extremely small in size but can be large in complexity!
 Animations can be played, resized, looped, sped up, slowed down, reversed, and even interactively scrubbed.
 Lottie can play or loop just a portion of the animation as well, the possibilities are endless!
 Animations can even be ***changed at runtime*** in various ways! Change the color, position or any keyframable value!
-Lottie also supports native UIViewController Transitions out of the box!
 
 Here is just a small sampling of the power of Lottie
 
@@ -26,10 +25,18 @@ Here is just a small sampling of the power of Lottie
 ![Abcs](_Gifs/Examples4.gif)
 
 ## Installing Lottie
-Lottie supports [CocoaPods](https://cocoapods.org/) and [Carthage](https://github.com/Carthage/Carthage) (Both dynamic and static). Lottie is written in ***Swift 4.2***.
+Lottie supports [Swift Package Manager](https://www.swift.org/package-manager/), [CocoaPods](https://cocoapods.org/) and [Carthage](https://github.com/Carthage/Carthage) (Both dynamic and static).
+
 ### Github Repo
 
-You can pull the [Lottie Github Repo](https://github.com/airbnb/lottie-ios/) and include the Lottie.xcodeproj to build a dynamic or static library.
+You can pull the [Lottie Github Repo](https://github.com/airbnb/lottie-ios/) and include the `Lottie.xcodeproj` to build a dynamic or static library.
+
+### Swift Package Manager
+
+To install Lottie using [Swift Package Manager](https://github.com/apple/swift-package-manager)  you can follow the [tutorial published by Apple](https://developer.apple.com/documentation/xcode/adding_package_dependencies_to_your_app) using the URL for the Lottie repo with the current version:
+
+1. In Xcode, select “File” → “Swift Packages” → “Add Package Dependency”
+1. Enter https://github.com/airbnb/lottie-ios.git
 
 ### CocoaPods
 Add the pod to your Podfile:
@@ -41,7 +48,7 @@ And then run:
 ```ruby
 pod install
 ```
-After installing the cocoapod into your project import Lottie with 
+After installing the cocoapod into your project import Lottie with
 ```swift
 import Lottie
 ```
@@ -57,60 +64,34 @@ carthage update
 ```
 In your application targets “General” tab under the “Linked Frameworks and Libraries” section, drag and drop lottie-ios.framework from the Carthage/Build/iOS directory that `carthage update` produced.
 
-### Swift Package Manager
-``` swift
-// swift-tools-version:5.1
-
-import PackageDescription
-
-let package = Package(
-  name: "YourTestProject",
-  platforms: [
-       .iOS(.v12),
-  ],
-  dependencies: [
-    .package(url: "https://github.com/airbnb/lottie-ios.git", from: "3.1.2")
-  ],
-  targets: [
-    .target(name: "YourTestProject", dependencies: ["Lottie"])
-  ]
-)
-```
-And then import wherever needed: ```import Lottie```
-
-#### Adding it to an existent iOS Project via Swift Package Manager
-
-1. Using Xcode 11 go to File > Swift Packages > Add Package Dependency
-2. Paste the project URL: https://github.com/airbnb/lottie-ios
-3. Click on next and select the project target
-4. Don't forget to set `DEAD_CODE_STRIPPING = NO` in your `Build Settings` (https://bugs.swift.org/plugins/servlet/mobile#issue/SR-11564)
-  **NOTE: For MacOS you must set the `Branch` field to `lottie/macos-spm`
-  ![Example](_Gifs/spm-branch.png)
-
-If you have doubts, please, check the following links:
-
-[How to use](https://developer.apple.com/videos/play/wwdc2019/408/)
-
-[Creating Swift Packages](https://developer.apple.com/videos/play/wwdc2019/410/)
-
-After successfully retrieved the package and added it to your project, just import `Lottie` and you can get the full benefits of it.
-
------
-
-### Objective-C Support
+### Data collection
 
-As of 3.0 Lottie has been completely rewritten in Swift! 
+The Lottie SDK does not collect any data. We provide this notice to help you fill out [App Privacy Details](https://developer.apple.com/app-store/app-privacy-details/).
 
-For Objective-C support please use Lottie 2.5.3. Alternatively an Objective-C branch exists and is still active.
+## Contributing
 
-The official objective c branch can be found here:
+We always appreciate contributions from the community. To make changes to the project, you can clone the repo and open `Lottie.xcworkspace`. This workspace includes:
+ - the Lottie framework (for iOS, macOS, and tvOS)
+ - unit tests and snapshot tests (for iOS, must be run on an iPhone 8 simulator)
+ - an Example iOS app that lets you browse and test over 100 sample animations included in the repo
 
-[Objective-C Branch](https://github.com/airbnb/lottie-ios/tree/lottie/objectiveC)
+All pull requests with new features or bug fixes that affect how animations render should include snapshot test cases that validate the included changes. 
+  - To add a new sample animation to the snapshot testing suite, you can add the `.json` file to `Tests/Samples`. Re-run the snapshot tests to generate the new snapshot image files.
+  - To update existing snapshots after making changes, you can set `isRecording = true` in `SnapshotTests.swift` and then re-run the snapshot tests.
 
-Also check out the documentation regarding it here: 
+The project also include several helpful commands defined in our [Rakefile](https://github.com/airbnb/lottie-ios/blob/master/Rakefile). To use these, you need to install [Bundler](https://bundler.io/) and [Mint](https://github.com/yonaskolb/Mint):
 
-[iOS Migration](http://airbnb.io/lottie/#/ios-migration)
+```bash
+$ sudo gem install bundle
+$ bundle install
+$ brew install mint
+```
 
-### Data collection
+For example, all Swift code should be formatted according to the [Airbnb Swift Style Guide](https://github.com/airbnb/swift). After making changes, you can reformat the code automatically using [SwiftFormat](https://github.com/nicklockwood/SwiftFormat) and [SwiftLint](https://github.com/realm/SwiftLint) by running `bundle exec rake format:swift`. Other helpful commands include:
 
-The Lottie SDK does not collect any data. We provide this notice to help you fill out [App Privacy Details](https://developer.apple.com/app-store/app-privacy-details/).
+```bash
+$ bundle exec rake build:all # builds all targets for all platforms
+$ bundle exec rake build:package:iOS # builds the Lottie package for iOS
+$ bundle exec rake test:package # tests the Lottie package
+$ bundle exec rake format:swift # reformat Swift code based on the Airbnb Swift Style Guide
+```

package/Rakefile

@@ -0,0 +1,125 @@
+namespace :build do
+  desc 'Builds all packages and executables'
+  task all: ['package:all', 'example:all']
+
+  desc 'Builds the Lottie package for supported platforms'
+  namespace :package do
+    desc 'Builds the Lottie package for all supported platforms'
+    task all: ['iOS', 'macOS', 'tvOS']
+
+    desc 'Builds the Lottie package for iOS'
+    task :iOS do
+      xcodebuild('build -scheme "Lottie (iOS)" -destination generic/platform=iOS -workspace Lottie.xcworkspace')
+    end
+
+    desc 'Builds the Lottie package for macOS'
+    task :macOS do
+      xcodebuild('build -scheme "Lottie (macOS)" -destination generic/platform=macOS -workspace Lottie.xcworkspace')
+    end
+
+    desc 'Builds the Lottie package for tvOS'
+    task :tvOS do
+      xcodebuild('build -scheme "Lottie (tvOS)" -destination generic/platform=tvOS -workspace Lottie.xcworkspace')
+    end
+  end
+
+  desc 'Builds the Lottie example app for supported platforms'
+  namespace :example do
+    desc 'Builds the Lottie example apps for all supported platforms'
+    task all: ['iOS', 'macOS', 'tvOS']
+
+    desc 'Builds the iOS Lottie Example app'
+    task :iOS do
+      xcodebuild('build -scheme "Example (iOS)" -destination "platform=iOS Simulator,name=iPhone 8" -workspace Lottie.xcworkspace')
+    end
+
+    desc 'Builds the macOS Lottie Example app'
+    task :macOS do
+      xcodebuild('build -scheme "Example (macOS)" -workspace Lottie.xcworkspace')
+    end
+
+    desc 'Builds the tvOS Lottie Example app'
+    task :tvOS do
+      xcodebuild('build -scheme "Example (tvOS)" -destination "platform=tvOS Simulator,name=Apple TV" -workspace Lottie.xcworkspace')
+    end
+  end
+end
+
+namespace :test do
+  desc 'Tests the Lottie package for iOS'
+  task :package do
+    sh 'rm -rf Tests/Artifacts'
+    xcodebuild('test -scheme "Lottie (iOS)" -destination "platform=iOS Simulator,name=iPhone 8" -resultBundlePath Tests/Artifacts/LottieTests.xcresult')
+  end
+
+  desc 'Processes .xcresult artifacts from the most recent test:package execution'
+  task :process do
+    sh 'mint run ChargePoint/xcparse@2.2.1 xcparse attachments Tests/Artifacts/LottieTests.xcresult Tests/Artifacts/TestAttachments'
+  end
+
+  desc 'Tests Carthage support'
+  task :carthage do
+    # Copy the repo to `Carthage/Checkouts/Lottie-ios`
+    sh 'rm -rf script/test-carthage/Carthage'
+    sh 'mkdir script/test-carthage/Carthage script/test-carthage/Carthage/Checkouts script/test-carthage/Carthage/Checkouts/lottie-ios'
+    sh 'cp -R [^script]* script/test-carthage/Carthage/Checkouts/lottie-ios'
+
+    Dir.chdir('script/test-carthage') do
+      # Build the LottieCarthage framework scheme
+      sh 'carthage build --use-xcframeworks'
+
+      # Delete Carthage's derived data to verify that the built .xcframework doesn't depend on any
+      # side effects from building on this specific machine.
+      # https://github.com/airbnb/lottie-ios/issues/1492
+      sh 'rm -rf ~/Library/Caches/org.carthage.CarthageKit/DerivedData'
+
+      # Build a test app that imports and uses the LottieCarthage framework
+      xcodebuild('build -scheme CarthageTest -destination "platform=iOS Simulator,name=iPhone 8"')
+    end
+  end
+
+  desc 'Tests Swift Package Manager support'
+  task :spm do
+    Dir.chdir('script/test-spm') do
+      # Build for iOS, macOS, and tvOS using the targets defined in Package.swift
+      xcodebuild('build -scheme "Lottie" -destination generic/platform=iOS')
+      xcodebuild('build -scheme "Lottie" -destination generic/platform=macOS')
+      xcodebuild('build -scheme "Lottie" -destination generic/platform=tvOS')
+    end
+  end
+end
+
+namespace :lint do
+  desc 'Lints swift files'
+  task swift: ['swift:swiftlint', 'swift:swiftformat']
+
+  desc 'Lints swift files'
+  namespace :swift do
+    desc 'Lints swift files using SwiftLint'
+    task :swiftlint do
+      sh 'mint run SwiftLint lint Sources Tests Example Package.swift --config script/lint/swiftlint.yml --strict'
+    end
+
+    desc 'Lints swift files using SwiftLint'
+    task :swiftformat do
+      sh 'mint run SwiftFormat Sources Tests Example Package.swift --config script/lint/airbnb.swiftformat --lint'
+    end
+  end
+
+  desc 'Lints the CocoaPods podspec'
+  task :podspec do
+    sh 'pod lib lint lottie-ios.podspec'
+  end
+end
+
+namespace :format do
+  desc 'Runs SwiftFormat'
+  task :swift do
+    sh 'mint run SwiftLint autocorrect Sources Tests Example Package.swift --config script/lint/swiftlint.yml'
+    sh 'mint run SwiftFormat Sources Tests Example Package.swift --config script/lint/airbnb.swiftformat'
+  end
+end
+
+def xcodebuild(command)
+  sh "set -o pipefail && xcodebuild #{command} | mint run xcbeautify"
+end

package/Sources/Private/CoreAnimation/Animations/CAAnimation+TimingConfiguration.swift

@@ -0,0 +1,76 @@
+// Created by Cal Stephens on 1/6/22.
+// Copyright © 2022 Airbnb Inc. All rights reserved.
+
+import QuartzCore
+
+extension CAAnimation {
+  /// Creates a `CAAnimation` that wraps this animation,
+  /// applying timing-related configuration from the given `LayerAnimationContext`
+  @nonobjc
+  func timed(with context: LayerAnimationContext, for layer: CALayer) -> CAAnimation {
+
+    // The base animation always has the duration of the full animation,
+    // since that's the time space where keyframing and interpolating happens.
+    // So we start with a simple animation timeline from 0% to 100%:
+    //
+    //  ┌──────────────────────────────────┐
+    //  │           baseAnimation          │
+    //  └──────────────────────────────────┘
+    //  0%                                100%
+    //
+    let baseAnimation = self
+    baseAnimation.duration = context.animation.duration
+    baseAnimation.speed = (context.endFrame < context.startFrame) ? -1 : 1
+
+    // To select the subrange of the `baseAnimation` that should be played,
+    // we create a parent animation with the duration of that subrange
+    // to clip the `baseAnimation`. This parent animation can then loop
+    // and/or autoreverse over the clipped subrange.
+    //
+    //        ┌────────────────────┬───────►
+    //        │   clippingParent   │  ...
+    //        └────────────────────┴───────►
+    //       25%                  75%
+    //  ┌──────────────────────────────────┐
+    //  │           baseAnimation          │
+    //  └──────────────────────────────────┘
+    //  0%                                100%
+    //
+    let clippingParent = CAAnimationGroup()
+    clippingParent.animations = [baseAnimation]
+
+    clippingParent.duration = Double(abs(context.endFrame - context.startFrame)) / context.animation.framerate
+    baseAnimation.timeOffset = context.animation.time(forFrame: context.startFrame)
+
+    clippingParent.autoreverses = context.timingConfiguration.autoreverses
+    clippingParent.repeatCount = context.timingConfiguration.repeatCount
+    clippingParent.timeOffset = context.timingConfiguration.timeOffset
+
+    // Once the animation ends, it should pause on the final frame
+    clippingParent.fillMode = .both
+    clippingParent.isRemovedOnCompletion = false
+
+    // We can pause the animation on a specific frame by setting the root layer's
+    // `speed` to 0, and then setting the `timeOffset` for the given frame.
+    //  - For that setup to work properly, we have to set the `beginTime`
+    //    of this animation to a time slightly before the current time.
+    //  - It's not really clear why this is necessary, but `timeOffset`
+    //    is not applied correctly without this configuration.
+    //  - We can't do this when playing the animation in real time,
+    //    because it can cause keyframe timings to be incorrect.
+    if context.timingConfiguration.speed == 0 {
+      let currentTime = layer.convertTime(CACurrentMediaTime(), from: nil)
+      clippingParent.beginTime = currentTime - .leastNonzeroMagnitude
+    }
+
+    return clippingParent
+  }
+}
+
+extension CALayer {
+  /// Adds the given animation to this layer, timed with the given timing configuration
+  @nonobjc
+  func add(_ animation: CAPropertyAnimation, timedWith context: LayerAnimationContext) {
+    add(animation.timed(with: context, for: self), forKey: animation.keyPath)
+  }
+}

package/Sources/Private/CoreAnimation/Animations/CALayer+addAnimation.swift

@@ -0,0 +1,322 @@
+// Created by Cal Stephens on 12/14/21.
+// Copyright © 2021 Airbnb Inc. All rights reserved.
+
+import QuartzCore
+
+extension CALayer {
+
+  // MARK: Internal
+
+  /// Constructs a `CAKeyframeAnimation` that reflects the given keyframes,
+  /// and adds it to this `CALayer`.
+  @nonobjc
+  func addAnimation<KeyframeValue, ValueRepresentation: Equatable>(
+    for property: LayerProperty<ValueRepresentation>,
+    keyframes: ContiguousArray<Keyframe<KeyframeValue>>,
+    value keyframeValueMapping: (KeyframeValue) throws -> ValueRepresentation,
+    context: LayerAnimationContext)
+    throws
+  {
+    if let customAnimation = try customizedAnimation(for: property, context: context) {
+      add(customAnimation, timedWith: context)
+    }
+
+    else if
+      let defaultAnimation = try defaultAnimation(
+        for: property,
+        keyframes: keyframes,
+        value: keyframeValueMapping,
+        context: context)
+    {
+      add(defaultAnimation, timedWith: context)
+    }
+  }
+
+  // MARK: Private
+
+  /// Constructs a `CAAnimation` that reflects the given keyframes
+  ///  - If the value can be applied directly to the CALayer using KVC,
+  ///    then no `CAAnimation` will be created and the value will be applied directly.
+  @nonobjc
+  private func defaultAnimation<KeyframeValue, ValueRepresentation>(
+    for property: LayerProperty<ValueRepresentation>,
+    keyframes: ContiguousArray<Keyframe<KeyframeValue>>,
+    value keyframeValueMapping: (KeyframeValue) throws -> ValueRepresentation,
+    context: LayerAnimationContext)
+    throws
+    -> CAPropertyAnimation?
+  {
+    guard !keyframes.isEmpty else { return nil }
+
+    // If there is exactly one keyframe value, we can improve performance
+    // by applying that value directly to the layer instead of creating
+    // a relatively expensive `CAKeyframeAnimation`.
+    if keyframes.count == 1 {
+      let keyframeValue = try keyframeValueMapping(keyframes[0].value)
+
+      // If the keyframe value is the same as the layer's default value for this property,
+      // then we can just ignore this set of keyframes.
+      if keyframeValue == property.defaultValue {
+        return nil
+      }
+
+      // If the property on the CALayer being animated hasn't been modified from the default yet,
+      // then we can apply the keyframe value directly to the layer using KVC instead
+      // of creating a `CAAnimation`.
+      if
+        let defaultValue = property.defaultValue,
+        defaultValue == value(forKey: property.caLayerKeypath) as? ValueRepresentation
+      {
+        setValue(keyframeValue, forKeyPath: property.caLayerKeypath)
+        return nil
+      }
+
+      // Otherwise, we still need to create a `CAAnimation`, but we can
+      // create a simple `CABasicAnimation` that is still less expensive
+      // than computing a `CAKeyframeAnimation`.
+      let animation = CABasicAnimation(keyPath: property.caLayerKeypath)
+      animation.fromValue = keyframeValue
+      animation.toValue = keyframeValue
+      return animation
+    }
+
+    return try keyframeAnimation(
+      for: property,
+      keyframes: keyframes,
+      value: keyframeValueMapping,
+      context: context)
+  }
+
+  /// A `CAAnimation` that applies the custom value from the `AnyValueProvider`
+  /// registered for this specific property's `AnimationKeypath`,
+  /// if one has been registered using `AnimationView.setValueProvider(_:keypath:)`.
+  @nonobjc
+  private func customizedAnimation<ValueRepresentation>(
+    for property: LayerProperty<ValueRepresentation>,
+    context: LayerAnimationContext)
+    throws
+    -> CAPropertyAnimation?
+  {
+    guard
+      let customizableProperty = property.customizableProperty,
+      let customKeyframes = try context.valueProviderStore.customKeyframes(
+        of: customizableProperty,
+        for: AnimationKeypath(keys: context.currentKeypath.keys + customizableProperty.name.map { $0.rawValue }),
+        context: context)
+    else { return nil }
+
+    // Since custom animations are overriding an existing animation,
+    // we always have to create a CAKeyframeAnimation for these instead of
+    // letting `defaultAnimation(...)` try to apply the value using KVC.
+    return try keyframeAnimation(
+      for: property,
+      keyframes: customKeyframes.keyframes,
+      value: { $0 },
+      context: context)
+  }
+
+  /// Creates a `CAKeyframeAnimation` for the given keyframes
+  private func keyframeAnimation<KeyframeValue, ValueRepresentation>(
+    for property: LayerProperty<ValueRepresentation>,
+    keyframes: ContiguousArray<Keyframe<KeyframeValue>>,
+    value keyframeValueMapping: (KeyframeValue) throws -> ValueRepresentation,
+    context: LayerAnimationContext)
+    throws
+    -> CAKeyframeAnimation
+  {
+    // Convert the list of `Keyframe<T>` into
+    // the representation used by `CAKeyframeAnimation`
+    var keyTimes = keyframes.map { keyframeModel -> NSNumber in
+      NSNumber(value: Float(context.progressTime(for: keyframeModel.time)))
+    }
+
+    var timingFunctions = self.timingFunctions(for: keyframes)
+    let calculationMode = try self.calculationMode(for: keyframes, context: context)
+
+    let animation = CAKeyframeAnimation(keyPath: property.caLayerKeypath)
+
+    // Position animations define a `CGPath` curve that should be followed,
+    // instead of animating directly between keyframe point values.
+    if property.caLayerKeypath == LayerProperty<CGPoint>.position.caLayerKeypath {
+      animation.path = try path(keyframes: keyframes, value: { value in
+        guard let point = try keyframeValueMapping(value) as? CGPoint else {
+          context.logger.assertionFailure("Cannot create point from keyframe with value \(value)")
+          return .zero
+        }
+
+        return point
+      })
+    }
+
+    // All other types of keyframes provide individual values that are interpolated by Core Animation
+    else {
+      var values = try keyframes.map { keyframeModel in
+        try keyframeValueMapping(keyframeModel.value)
+      }
+
+      validate(
+        values: &values,
+        keyTimes: &keyTimes,
+        timingFunctions: &timingFunctions,
+        for: calculationMode,
+        context: context)
+
+      animation.values = values
+    }
+
+    animation.calculationMode = calculationMode
+    animation.keyTimes = keyTimes
+    animation.timingFunctions = timingFunctions
+    return animation
+  }
+
+  /// The `CAAnimationCalculationMode` that should be used for a `CAKeyframeAnimation`
+  /// animating the given keyframes
+  private func calculationMode<KeyframeValue>(
+    for keyframes: ContiguousArray<Keyframe<KeyframeValue>>,
+    context: LayerAnimationContext)
+    throws
+    -> CAAnimationCalculationMode
+  {
+    // Animations using `isHold` should use `CAAnimationCalculationMode.discrete`
+    //
+    //  - Since we currently only create a single `CAKeyframeAnimation`,
+    //    we can currently only correctly support animations where
+    //    `isHold` is either always `true` or always `false`
+    //    (this requirement doesn't apply to the first/last keyframes).
+    //
+    //  - We should be able to support this in the future by creating multiple
+    //    `CAKeyframeAnimation`s with different `calculationMode`s and
+    //    playing them sequentially.
+    //
+    let intermediateKeyframes = keyframes.dropFirst().dropLast()
+    if intermediateKeyframes.contains(where: \.isHold) {
+      if intermediateKeyframes.allSatisfy(\.isHold) {
+        return .discrete
+      } else {
+        try context.logCompatibilityIssue("Mixed `isHold` / `!isHold` keyframes are currently unsupported")
+      }
+    }
+
+    return .linear
+  }
+
+  /// `timingFunctions` to apply to a `CAKeyframeAnimation` animating the given keyframes
+  private func timingFunctions<KeyframeValue>(
+    for keyframes: ContiguousArray<Keyframe<KeyframeValue>>)
+    -> [CAMediaTimingFunction]
+  {
+    // Compute the timing function between each keyframe and the subsequent keyframe
+    var timingFunctions: [CAMediaTimingFunction] = []
+
+    for (index, keyframe) in keyframes.enumerated()
+      where index != keyframes.indices.last
+    {
+      let nextKeyframe = keyframes[index + 1]
+
+      let controlPoint1 = keyframe.outTangent?.pointValue ?? .zero
+      let controlPoint2 = nextKeyframe.inTangent?.pointValue ?? CGPoint(x: 1, y: 1)
+
+      timingFunctions.append(CAMediaTimingFunction(
+        controlPoints:
+        Float(controlPoint1.x),
+        Float(controlPoint1.y),
+        Float(controlPoint2.x),
+        Float(controlPoint2.y)))
+    }
+
+    return timingFunctions
+  }
+
+  /// Creates a `CGPath` for the given `position` keyframes,
+  /// which accounts for `spatialInTangent`s and `spatialOutTangents`
+  private func path<KeyframeValue>(
+    keyframes positionKeyframes: ContiguousArray<Keyframe<KeyframeValue>>,
+    value keyframeValueMapping: (KeyframeValue) throws -> CGPoint) rethrows
+    -> CGPath {
+    let path = CGMutablePath()
+
+    for (index, keyframe) in positionKeyframes.enumerated() {
+      if index == positionKeyframes.indices.first {
+        path.move(to: try keyframeValueMapping(keyframe.value))
+      }
+
+      if index != positionKeyframes.indices.last {
+        let nextKeyframe = positionKeyframes[index + 1]
+
+        if
+          let controlPoint1 = keyframe.spatialOutTangent?.pointValue,
+          let controlPoint2 = nextKeyframe.spatialInTangent?.pointValue,
+          controlPoint1 != .zero,
+          controlPoint2 != .zero
+        {
+          path.addCurve(
+            to: try keyframeValueMapping(nextKeyframe.value),
+            control1: try keyframeValueMapping(keyframe.value) + controlPoint1,
+            control2: try keyframeValueMapping(nextKeyframe.value) + controlPoint2)
+        }
+
+        else {
+          path.addLine(to: try keyframeValueMapping(nextKeyframe.value))
+        }
+      }
+    }
+
+    path.closeSubpath()
+    return path
+  }
+
+  /// Validates that the requirements of the `CAKeyframeAnimation` API are met correctly
+  private func validate<ValueRepresentation>(
+    values: inout [ValueRepresentation],
+    keyTimes: inout [NSNumber],
+    timingFunctions: inout [CAMediaTimingFunction],
+    for calculationMode: CAAnimationCalculationMode,
+    context: LayerAnimationContext)
+  {
+    // Validate that we have correct start (0.0) and end (1.0) keyframes.
+    // From the documentation of `CAKeyframeAnimation.keyTimes`:
+    //  - The first value in the `keyTimes` array must be 0.0 and the last value must be 1.0.
+    if keyTimes.first != 0.0 {
+      keyTimes.insert(0.0, at: 0)
+      values.insert(values[0], at: 0)
+      timingFunctions.insert(CAMediaTimingFunction(name: .linear), at: 0)
+    }
+
+    if keyTimes.last != 1.0 {
+      keyTimes.append(1.0)
+      values.append(values.last!)
+      timingFunctions.append(CAMediaTimingFunction(name: .linear))
+    }
+
+    switch calculationMode {
+    case .linear, .cubic:
+      // From the documentation of `CAKeyframeAnimation.keyTimes`:
+      //  - The number of elements in the keyTimes array
+      //    should match the number of elements in the values property
+      context.logger.assert(
+        values.count == keyTimes.count,
+        "`values.count` must exactly equal `keyTimes.count`")
+
+      context.logger.assert(
+        timingFunctions.count == (values.count - 1),
+        "`timingFunctions.count` must exactly equal `values.count - 1`")
+
+    case .discrete:
+      // From the documentation of `CAKeyframeAnimation.keyTimes`:
+      //  - If the calculationMode is set to discrete... the keyTimes array
+      //    should have one more entry than appears in the values array.
+      values.removeLast()
+
+      context.logger.assert(
+        keyTimes.count == values.count + 1,
+        "`keyTimes.count` must exactly equal `values.count + 1`")
+
+    default:
+      context.logger.assertionFailure("""
+        Unexpected keyframe calculation mode \(calculationMode)
+        """)
+    }
+  }
+
+}