lottie-ios 4.2.0 → 4.3.1

package/Sources/Private/CoreAnimation/Animations/LayerProperty.swift

@@ -26,6 +26,16 @@ struct LayerProperty<ValueRepresentation> {
 }
 
 extension LayerProperty where ValueRepresentation: Equatable {
+  /// Initializes a `LayerProperty` that corresponds to a property on `CALayer`
+  /// or some other `CALayer` subclass like `CAShapeLayer`.
+  /// - Parameters:
+  ///   - caLayerKeypath: The Objective-C `#keyPath` to the `CALayer` property,
+  ///     e.g. `#keyPath(CALayer.opacity)` or `#keyPath(CAShapeLayer.path)`.
+  ///   - defaultValue: The default value of the property (e.g. the value of the
+  ///     property immediately after calling `CALayer.init()`). Knowing this value
+  ///     lets us perform some optimizations in `CALayer+addAnimation`.
+  ///   - customizableProperty: A description of how this property can be customized
+  ///     dynamically at runtime using `AnimationView.setValueProvider(_:keypath:)`.
   init(
     caLayerKeypath: String,
     defaultValue: ValueRepresentation?,
@@ -52,7 +62,10 @@ struct CustomizableProperty<ValueRepresentation> {
 
   /// A closure that coverts the type-erased value of an `AnyValueProvider`
   /// to the strongly-typed representation used by this property, if possible.
-  let conversion: (Any) -> ValueRepresentation?
+  ///  - `value` is the value for the current frame that should be converted,
+  ///    as returned by `AnyValueProvider.typeErasedStorage`.
+  ///  - `valueProvider` is the `AnyValueProvider` that returned the type-erased value.
+  let conversion: (_ value: Any, _ valueProvider: AnyValueProvider) -> ValueRepresentation?
 }
 
 // MARK: - PropertyName
@@ -66,6 +79,8 @@ enum PropertyName: String, CaseIterable {
   case scale = "Scale"
   case position = "Position"
   case rotation = "Rotation"
+  case strokeWidth = "Stroke Width"
+  case gradientColors = "Colors"
 }
 
 // MARK: CALayer properties
@@ -159,6 +174,34 @@ extension LayerProperty {
       },
       customizableProperty: nil /* currently unsupported */ )
   }
+
+  static var shadowOpacity: LayerProperty<CGFloat> {
+    .init(
+      caLayerKeypath: #keyPath(CALayer.shadowOpacity),
+      defaultValue: 0,
+      customizableProperty: nil /* currently unsupported */ )
+  }
+
+  static var shadowColor: LayerProperty<CGColor> {
+    .init(
+      caLayerKeypath: #keyPath(CALayer.shadowColor),
+      defaultValue: .rgb(0, 0, 0),
+      customizableProperty: nil /* currently unsupported */ )
+  }
+
+  static var shadowRadius: LayerProperty<CGFloat> {
+    .init(
+      caLayerKeypath: #keyPath(CALayer.shadowRadius),
+      defaultValue: 3.0,
+      customizableProperty: nil /* currently unsupported */ )
+  }
+
+  static var shadowOffset: LayerProperty<CGSize> {
+    .init(
+      caLayerKeypath: #keyPath(CALayer.shadowOffset),
+      defaultValue: CGSize(width: 0, height: -3.0),
+      customizableProperty: nil /* currently unsupported */ )
+  }
 }
 
 // MARK: CAShapeLayer properties
@@ -182,7 +225,7 @@ extension LayerProperty {
     .init(
       caLayerKeypath: #keyPath(CAShapeLayer.lineWidth),
       defaultValue: 1,
-      customizableProperty: nil /* currently unsupported */ )
+      customizableProperty: .floatValue(.strokeWidth))
   }
 
   static var lineDashPhase: LayerProperty<CGFloat> {
@@ -221,14 +264,14 @@ extension LayerProperty {
     .init(
       caLayerKeypath: #keyPath(CAGradientLayer.colors),
       defaultValue: nil,
-      customizableProperty: nil /* currently unsupported */ )
+      customizableProperty: .gradientColors)
   }
 
   static var locations: LayerProperty<[CGFloat]> {
     .init(
       caLayerKeypath: #keyPath(CAGradientLayer.locations),
       defaultValue: nil,
-      customizableProperty: nil /* currently unsupported */ )
+      customizableProperty: .gradientLocations)
   }
 
   static var startPoint: LayerProperty<CGPoint> {
@@ -252,7 +295,7 @@ extension CustomizableProperty {
   static var color: CustomizableProperty<CGColor> {
     .init(
       name: [.color],
-      conversion: { typeErasedValue in
+      conversion: { typeErasedValue, _ in
         guard let color = typeErasedValue as? LottieColor else {
           return nil
         }
@@ -264,7 +307,7 @@ extension CustomizableProperty {
   static var opacity: CustomizableProperty<CGFloat> {
     .init(
       name: [.opacity],
-      conversion: { typeErasedValue in
+      conversion: { typeErasedValue, _ in
         guard let vector = typeErasedValue as? LottieVector1D else { return nil }
 
         // Lottie animation files express opacity as a numerical percentage value
@@ -277,7 +320,7 @@ extension CustomizableProperty {
   static var scaleX: CustomizableProperty<CGFloat> {
     .init(
       name: [.scale],
-      conversion: { typeErasedValue in
+      conversion: { typeErasedValue, _ in
         guard let vector = typeErasedValue as? LottieVector3D else { return nil }
 
         // Lottie animation files express scale as a numerical percentage value
@@ -290,7 +333,7 @@ extension CustomizableProperty {
   static var scaleY: CustomizableProperty<CGFloat> {
     .init(
       name: [.scale],
-      conversion: { typeErasedValue in
+      conversion: { typeErasedValue, _ in
         guard let vector = typeErasedValue as? LottieVector3D else { return nil }
 
         // Lottie animation files express scale as a numerical percentage value
@@ -303,7 +346,7 @@ extension CustomizableProperty {
   static var rotation: CustomizableProperty<CGFloat> {
     .init(
       name: [.rotation],
-      conversion: { typeErasedValue in
+      conversion: { typeErasedValue, _ in
         guard let vector = typeErasedValue as? LottieVector1D else { return nil }
 
         // Lottie animation files express rotation in degrees
@@ -316,6 +359,36 @@ extension CustomizableProperty {
   static var position: CustomizableProperty<CGPoint> {
     .init(
       name: [.position],
-      conversion: { ($0 as? LottieVector3D)?.pointValue })
+      conversion: { typeErasedValue, _ in
+        guard let vector = typeErasedValue as? LottieVector3D else { return nil }
+        return vector.pointValue
+      })
+  }
+
+  static var gradientColors: CustomizableProperty<[CGColor]> {
+    .init(
+      name: [.gradientColors],
+      conversion: { _, typeErasedValueProvider in
+        guard let gradientValueProvider = typeErasedValueProvider as? GradientValueProvider else { return nil }
+        return gradientValueProvider.colors.map { $0.cgColorValue }
+      })
+  }
+
+  static var gradientLocations: CustomizableProperty<[CGFloat]> {
+    .init(
+      name: [.gradientColors],
+      conversion: { _, typeErasedValueProvider in
+        guard let gradientValueProvider = typeErasedValueProvider as? GradientValueProvider else { return nil }
+        return gradientValueProvider.locations.map { CGFloat($0) }
+      })
+  }
+
+  static func floatValue(_ name: PropertyName...) -> CustomizableProperty<CGFloat> {
+    .init(
+      name: name,
+      conversion: { typeErasedValue, _ in
+        guard let vector = typeErasedValue as? LottieVector1D else { return nil }
+        return vector.cgFloatValue
+      })
   }
 }

package/Sources/Private/CoreAnimation/Animations/TransformAnimations.swift

@@ -6,7 +6,7 @@ import QuartzCore
 // MARK: - TransformModel
 
 /// This protocol mirrors the interface of `Transform`,
-/// but it also implemented by `ShapeTransform` to allow
+/// but is also implemented by `ShapeTransform` to allow
 /// both transform types to share the same animation implementation.
 protocol TransformModel {
   /// The anchor point of the transform.
@@ -32,6 +32,12 @@ protocol TransformModel {
 
   /// The rotation of the transform on Z axis.
   var rotationZ: KeyframeGroup<LottieVector1D> { get }
+
+  /// The skew of the transform (only present on `ShapeTransform`s)
+  var _skew: KeyframeGroup<LottieVector1D>? { get }
+
+  /// The skew axis of the transform (only present on `ShapeTransform`s)
+  var _skewAxis: KeyframeGroup<LottieVector1D>? { get }
 }
 
 // MARK: - Transform + TransformModel
@@ -40,6 +46,8 @@ extension Transform: TransformModel {
   var _position: KeyframeGroup<LottieVector3D>? { position }
   var _positionX: KeyframeGroup<LottieVector1D>? { positionX }
   var _positionY: KeyframeGroup<LottieVector1D>? { positionY }
+  var _skew: KeyframeGroup<LottieVector1D>? { nil }
+  var _skewAxis: KeyframeGroup<LottieVector1D>? { nil }
 }
 
 // MARK: - ShapeTransform + TransformModel
@@ -49,6 +57,8 @@ extension ShapeTransform: TransformModel {
   var _position: KeyframeGroup<LottieVector3D>? { position }
   var _positionX: KeyframeGroup<LottieVector1D>? { nil }
   var _positionY: KeyframeGroup<LottieVector1D>? { nil }
+  var _skew: KeyframeGroup<LottieVector1D>? { skew }
+  var _skewAxis: KeyframeGroup<LottieVector1D>? { skewAxis }
 }
 
 // MARK: - CALayer + TransformModel
@@ -66,15 +76,18 @@ extension CALayer {
     context: LayerAnimationContext)
     throws
   {
-    // CALayers don't support animating skew with its own set of keyframes.
-    // If the transform includes a skew, we have to combine all of the transform
-    // components into a single set of keyframes.
-    // Only `ShapeTransform` supports skews.
     if
-      let shapeTransform = transformModel as? ShapeTransform,
-      shapeTransform.hasSkew
+      // CALayers don't support animating skew with its own set of keyframes.
+      // If the transform includes a skew, we have to combine all of the transform
+      // components into a single set of keyframes.
+      transformModel.hasSkew
+      // Negative `scale.x` values aren't applied correctly by Core Animation when animating
+      // `transform.scale.x` and `transform.scale.y` using separate `CAKeyframeAnimation`s
+      // (https://openradar.appspot.com/FB9862872). If the transform includes negative `scale.x`
+      // values, we have to combine all of the transform components into a single set of keyframes.
+      || transformModel.hasNegativeXScaleValues
     {
-      try addCombinedTransformAnimation(for: shapeTransform, context: context)
+      try addCombinedTransformAnimation(for: transformModel, context: context)
     }
 
     else {
@@ -159,65 +172,10 @@ extension CALayer {
         // Lottie animation files express scale as a numerical percentage value
         // (e.g. 50%, 100%, 200%) so we divide by 100 to get the decimal values
         // expected by Core Animation (e.g. 0.5, 1.0, 2.0).
-        //  - Negative `scale.x` values aren't applied correctly by Core Animation.
-        //    This appears to be because we animate `transform.scale.x` and `transform.scale.y`
-        //    as separate `CAKeyframeAnimation`s instead of using a single animation of `transform` itself.
-        //    https://openradar.appspot.com/FB9862872
-        //  - To work around this, we set up a `rotationY` animation below
-        //    to flip the view horizontally, which gives us the desired effect.
-        abs(CGFloat(scale.x) / 100)
+        CGFloat(scale.x) / 100
       },
       context: context)
 
-    /// iOS 14 and earlier doesn't properly support rendering transforms with
-    /// negative `scale.x` values: https://github.com/airbnb/lottie-ios/issues/1882
-    let osSupportsNegativeScaleValues: Bool = {
-      #if os(iOS) || os(tvOS)
-      if #available(iOS 15.0, tvOS 15.0, *) {
-        return true
-      } else {
-        return false
-      }
-      #else
-      // We'll assume this works correctly on macOS until told otherwise
-      return true
-      #endif
-    }()
-
-    lazy var hasNegativeXScaleValues = transformModel.scale.keyframes.contains(where: { $0.value.x < 0 })
-
-    // When `scale.x` is negative, we have to rotate the view
-    // half way around the y axis to flip it horizontally.
-    //  - We don't do this in snapshot tests because it breaks the tests
-    //    in surprising ways that don't happen at runtime. Definitely not ideal.
-    //  - This isn't supported on iOS 14 and earlier either, so we have to
-    //    log a compatibility error on devices running older OSs.
-    if TestHelpers.snapshotTestsAreRunning {
-      if hasNegativeXScaleValues {
-        context.logger.warn("""
-          Negative `scale.x` values are not displayed correctly in snapshot tests
-          """)
-      }
-    } else {
-      if !osSupportsNegativeScaleValues, hasNegativeXScaleValues {
-        try context.logCompatibilityIssue("""
-          iOS 14 and earlier does not support rendering negative `scale.x` values
-          """)
-      }
-
-      try addAnimation(
-        for: .rotationY,
-        keyframes: transformModel.scale,
-        value: { scale in
-          if scale.x < 0 {
-            return .pi
-          } else {
-            return 0
-          }
-        },
-        context: context)
-    }
-
     try addAnimation(
       for: .scaleY,
       keyframes: transformModel.scale,
@@ -225,9 +183,6 @@ extension CALayer {
         // Lottie animation files express scale as a numerical percentage value
         // (e.g. 50%, 100%, 200%) so we divide by 100 to get the decimal values
         // expected by Core Animation (e.g. 0.5, 1.0, 2.0).
-        //  - Negative `scaleY` values are correctly applied (they flip the view
-        //    vertically), so we don't have to apply an additional rotation animation
-        //    like we do for `scaleX`.
         CGFloat(scale.y) / 100
       },
       context: context)
@@ -258,7 +213,7 @@ extension CALayer {
     }
 
     // Lottie animation files express rotation in degrees
-    // (e.g. 90º, 180º, 360º) so we covert to radians to get the
+    // (e.g. 90º, 180º, 360º) so we convert to radians to get the
     // values expected by Core Animation (e.g. π/2, π, 2π)
 
     try addAnimation(
@@ -282,7 +237,7 @@ extension CALayer {
       keyframes: transformModel.rotationZ,
       value: { rotationDegrees in
         // Lottie animation files express rotation in degrees
-        // (e.g. 90º, 180º, 360º) so we covert to radians to get the
+        // (e.g. 90º, 180º, 360º) so we convert to radians to get the
         // values expected by Core Animation (e.g. π/2, π, 2π)
         rotationDegrees.cgFloatValue * .pi / 180
       },
@@ -291,26 +246,44 @@ extension CALayer {
 
   /// Adds an animation for the entire `transform` key by combining all of the
   /// position / size / rotation / skew animations into a single set of keyframes.
-  /// This is necessary when there's a skew animation, since skew can only
-  /// be applied via a transform.
+  /// This is more expensive that animating each component separately, since
+  /// it may require manually interpolating the keyframes at each frame.
   private func addCombinedTransformAnimation(
-    for transformModel: ShapeTransform,
+    for transformModel: TransformModel,
     context: LayerAnimationContext)
     throws
   {
+    // Core Animation doesn't animate skew changes properly. If the skew value
+    // changes over the course of the animation then we have to manually
+    // compute the `CATransform3D` for each frame individually.
+    let requiresManualInterpolation = transformModel.hasSkewAnimation
+
     let combinedTransformKeyframes = Keyframes.combined(
-      transformModel.anchor,
-      transformModel.position,
+      transformModel.anchorPoint,
+      transformModel._position ?? KeyframeGroup(LottieVector3D(x: 0.0, y: 0.0, z: 0.0)),
+      transformModel._positionX ?? KeyframeGroup(LottieVector1D(0)),
+      transformModel._positionY ?? KeyframeGroup(LottieVector1D(0)),
       transformModel.scale,
       transformModel.rotationX,
       transformModel.rotationY,
       transformModel.rotationZ,
-      transformModel.skew,
-      transformModel.skewAxis,
-      makeCombinedResult: { anchor, position, scale, rotationX, rotationY, rotationZ, skew, skewAxis in
-        CATransform3D.makeTransform(
+      transformModel._skew ?? KeyframeGroup(LottieVector1D(0)),
+      transformModel._skewAxis ?? KeyframeGroup(LottieVector1D(0)),
+      requiresManualInterpolation: requiresManualInterpolation,
+      makeCombinedResult: {
+        anchor, position, positionX, positionY, scale, rotationX, rotationY, rotationZ, skew, skewAxis
+          -> CATransform3D in
+
+        let transformPosition: CGPoint
+        if transformModel._positionX != nil, transformModel._positionY != nil {
+          transformPosition = CGPoint(x: positionX.cgFloatValue, y: positionY.cgFloatValue)
+        } else {
+          transformPosition = position.pointValue
+        }
+
+        return CATransform3D.makeTransform(
           anchor: anchor.pointValue,
-          position: position.pointValue,
+          position: transformPosition,
           scale: scale.sizeValue,
           rotationX: rotationX.cgFloatValue,
           rotationY: rotationY.cgFloatValue,
@@ -327,3 +300,36 @@ extension CALayer {
   }
 
 }
+
+extension TransformModel {
+  /// Whether or not this transform has a non-zero skew value
+  var hasSkew: Bool {
+    guard
+      let _skew = _skew,
+      let _skewAxis = _skewAxis,
+      !_skew.keyframes.isEmpty,
+      !_skewAxis.keyframes.isEmpty
+    else {
+      return false
+    }
+
+    return _skew.keyframes.contains(where: { $0.value.cgFloatValue != 0 })
+  }
+
+  /// Whether or not this transform has a non-zero skew value which animates
+  var hasSkewAnimation: Bool {
+    guard
+      hasSkew,
+      let _skew = _skew,
+      let _skewAxis = _skewAxis
+    else { return false }
+
+    return _skew.keyframes.count > 1
+      || _skewAxis.keyframes.count > 1
+  }
+
+  /// Whether or not this `TransformModel` has any negative X scale values
+  var hasNegativeXScaleValues: Bool {
+    scale.keyframes.contains(where: { $0.value.x < 0 })
+  }
+}

package/Sources/Private/CoreAnimation/CoreAnimationLayer.swift

@@ -17,7 +17,7 @@ final class CoreAnimationLayer: BaseAnimationLayer {
   init(
     animation: LottieAnimation,
     imageProvider: AnimationImageProvider,
-    textProvider: AnimationTextProvider,
+    textProvider: AnimationKeypathTextProvider,
     fontProvider: AnimationFontProvider,
     maskAnimationToBounds: Bool,
     compatibilityTrackerMode: CompatibilityTracker.Mode,
@@ -94,8 +94,8 @@ final class CoreAnimationLayer: BaseAnimationLayer {
     }
   }
 
-  /// The parent `LottieAnimationView` that manages this layer
-  weak var animationView: LottieAnimationView?
+  /// The parent `LottieAnimationLayer` that manages this layer
+  weak var lottieAnimationLayer: LottieAnimationLayer?
 
   /// A closure that is called after this layer sets up its animation.
   /// If the animation setup was unsuccessful and encountered compatibility issues,
@@ -108,9 +108,9 @@ final class CoreAnimationLayer: BaseAnimationLayer {
     didSet { reloadImages() }
   }
 
-  /// The `AnimationTextProvider` that `TextLayer`'s use to retrieve texts,
+  /// The `AnimationKeypathTextProvider` that `TextLayer`'s use to retrieve texts,
   /// that they should use to render their text context
-  var textProvider: AnimationTextProvider {
+  var textProvider: AnimationKeypathTextProvider {
     didSet {
       // We need to rebuild the current animation after updating the text provider,
       // since this is used in `TextLayer.setupAnimations(context:)`
@@ -209,6 +209,7 @@ final class CoreAnimationLayer: BaseAnimationLayer {
   private let valueProviderStore: ValueProviderStore
   private let compatibilityTracker: CompatibilityTracker
   private let logger: LottieLogger
+  private let loggingState = LoggingState()
 
   /// The current playback state of the animation that is displayed in this layer
   private var currentPlaybackState: PlaybackState? {
@@ -265,6 +266,7 @@ final class CoreAnimationLayer: BaseAnimationLayer {
       valueProviderStore: valueProviderStore,
       compatibilityTracker: compatibilityTracker,
       logger: logger,
+      loggingState: loggingState,
       currentKeypath: AnimationKeypath(keys: []),
       textProvider: textProvider,
       recordHierarchyKeypath: configuration.recordHierarchyKeypath)
@@ -316,7 +318,7 @@ final class CoreAnimationLayer: BaseAnimationLayer {
     else { return }
 
     if isAnimationPlaying == true {
-      animationView?.updateInFlightAnimation()
+      lottieAnimationLayer?.updateInFlightAnimation()
     } else {
       let currentFrame = currentFrame
       removeAnimations()
@@ -449,7 +451,9 @@ extension CoreAnimationLayer: RootAnimationLayer {
   }
 
   func forceDisplayUpdate() {
-    // Unimplemented / unused
+    // Unimplemented
+    //  - We can't call `display()` here, because it would cause unexpected frame animations:
+    //    https://github.com/airbnb/lottie-ios/issues/2193
   }
 
   func logHierarchyKeypaths() {

package/Sources/Private/CoreAnimation/Extensions/Keyframes+combined.swift

@@ -10,12 +10,18 @@ enum Keyframes {
   /// Combines the given keyframe groups of `Keyframe<T>`s into a single keyframe group of of `Keyframe<[T]>`s
   ///  - If all of the `KeyframeGroup`s have the exact same animation timing, the keyframes are merged
   ///  - Otherwise, the keyframes are manually interpolated at each frame in the animation
-  static func combined<T>(_ allGroups: [KeyframeGroup<T>]) -> KeyframeGroup<[T]>
+  static func combined<T>(
+    _ allGroups: [KeyframeGroup<T>],
+    requiresManualInterpolation: Bool = false)
+    -> KeyframeGroup<[T]>
     where T: AnyInterpolatable
   {
-    Keyframes.combined(allGroups, makeCombinedResult: { untypedValues in
-      untypedValues.compactMap { $0 as? T }
-    })
+    Keyframes.combined(
+      allGroups,
+      requiresManualInterpolation: requiresManualInterpolation,
+      makeCombinedResult: { untypedValues in
+        untypedValues.compactMap { $0 as? T }
+      })
   }
 
   /// Combines the given keyframe groups of `Keyframe<T>`s into a single keyframe group of of `Keyframe<[T]>`s
@@ -24,6 +30,7 @@ enum Keyframes {
   static func combined<T1, T2, CombinedResult>(
     _ k1: KeyframeGroup<T1>,
     _ k2: KeyframeGroup<T2>,
+    requiresManualInterpolation: Bool = false,
     makeCombinedResult: (T1, T2) throws -> CombinedResult)
     rethrows
     -> KeyframeGroup<CombinedResult>
@@ -31,6 +38,7 @@ enum Keyframes {
   {
     try Keyframes.combined(
       [k1, k2],
+      requiresManualInterpolation: requiresManualInterpolation,
       makeCombinedResult: { untypedValues in
         guard
           let t1 = untypedValues[0] as? T1,
@@ -48,12 +56,14 @@ enum Keyframes {
     _ k1: KeyframeGroup<T1>,
     _ k2: KeyframeGroup<T2>,
     _ k3: KeyframeGroup<T3>,
+    requiresManualInterpolation: Bool = false,
     makeCombinedResult: (T1, T2, T3) -> CombinedResult)
     -> KeyframeGroup<CombinedResult>
     where T1: AnyInterpolatable, T2: AnyInterpolatable, T3: AnyInterpolatable
   {
     Keyframes.combined(
       [k1, k2, k3],
+      requiresManualInterpolation: requiresManualInterpolation,
       makeCombinedResult: { untypedValues in
         guard
           let t1 = untypedValues[0] as? T1,
@@ -76,6 +86,7 @@ enum Keyframes {
     _ k5: KeyframeGroup<T5>,
     _ k6: KeyframeGroup<T6>,
     _ k7: KeyframeGroup<T7>,
+    requiresManualInterpolation: Bool = false,
     makeCombinedResult: (T1, T2, T3, T4, T5, T6, T7) -> CombinedResult)
     -> KeyframeGroup<CombinedResult>
     where T1: AnyInterpolatable, T2: AnyInterpolatable, T3: AnyInterpolatable, T4: AnyInterpolatable,
@@ -83,6 +94,7 @@ enum Keyframes {
   {
     Keyframes.combined(
       [k1, k2, k3, k4, k5, k6, k7],
+      requiresManualInterpolation: requiresManualInterpolation,
       makeCombinedResult: { untypedValues in
         guard
           let t1 = untypedValues[0] as? T1,
@@ -110,6 +122,7 @@ enum Keyframes {
     _ k6: KeyframeGroup<T6>,
     _ k7: KeyframeGroup<T7>,
     _ k8: KeyframeGroup<T8>,
+    requiresManualInterpolation: Bool = false,
     makeCombinedResult: (T1, T2, T3, T4, T5, T6, T7, T8) -> CombinedResult)
     -> KeyframeGroup<CombinedResult>
     where T1: AnyInterpolatable, T2: AnyInterpolatable, T3: AnyInterpolatable, T4: AnyInterpolatable,
@@ -117,6 +130,7 @@ enum Keyframes {
   {
     Keyframes.combined(
       [k1, k2, k3, k4, k5, k6, k7, k8],
+      requiresManualInterpolation: requiresManualInterpolation,
       makeCombinedResult: { untypedValues in
         guard
           let t1 = untypedValues[0] as? T1,
@@ -133,6 +147,48 @@ enum Keyframes {
       })
   }
 
+  /// Combines the given keyframe groups of `Keyframe<T>`s into a single keyframe group of of `Keyframe<[T]>`s
+  ///  - If all of the `KeyframeGroup`s have the exact same animation timing, the keyframes are merged
+  ///  - Otherwise, the keyframes are manually interpolated at each frame in the animation
+  static func combined<T1, T2, T3, T4, T5, T6, T7, T8, T9, T10, CombinedResult>(
+    _ k1: KeyframeGroup<T1>,
+    _ k2: KeyframeGroup<T2>,
+    _ k3: KeyframeGroup<T3>,
+    _ k4: KeyframeGroup<T4>,
+    _ k5: KeyframeGroup<T5>,
+    _ k6: KeyframeGroup<T6>,
+    _ k7: KeyframeGroup<T7>,
+    _ k8: KeyframeGroup<T8>,
+    _ k9: KeyframeGroup<T9>,
+    _ k10: KeyframeGroup<T10>,
+    requiresManualInterpolation: Bool = false,
+    makeCombinedResult: (T1, T2, T3, T4, T5, T6, T7, T8, T9, T10) -> CombinedResult)
+    -> KeyframeGroup<CombinedResult>
+    where T1: AnyInterpolatable, T2: AnyInterpolatable, T3: AnyInterpolatable, T4: AnyInterpolatable,
+    T5: AnyInterpolatable, T6: AnyInterpolatable, T7: AnyInterpolatable, T8: AnyInterpolatable,
+    T9: AnyInterpolatable, T10: AnyInterpolatable
+  {
+    Keyframes.combined(
+      [k1, k2, k3, k4, k5, k6, k7, k8, k9, k10],
+      requiresManualInterpolation: requiresManualInterpolation,
+      makeCombinedResult: { untypedValues in
+        guard
+          let t1 = untypedValues[0] as? T1,
+          let t2 = untypedValues[1] as? T2,
+          let t3 = untypedValues[2] as? T3,
+          let t4 = untypedValues[3] as? T4,
+          let t5 = untypedValues[4] as? T5,
+          let t6 = untypedValues[5] as? T6,
+          let t7 = untypedValues[6] as? T7,
+          let t8 = untypedValues[7] as? T8,
+          let t9 = untypedValues[8] as? T9,
+          let t10 = untypedValues[9] as? T10
+        else { return nil }
+
+        return makeCombinedResult(t1, t2, t3, t4, t5, t6, t7, t8, t9, t10)
+      })
+  }
+
   // MARK: Private
 
   /// Combines the given `[KeyframeGroup]` of `Keyframe<T>`s into a single `KeyframeGroup` of `Keyframe<CombinedResult>`s
@@ -141,8 +197,12 @@ enum Keyframes {
   ///
   /// `makeCombinedResult` is a closure that takes an array of keyframe values (with the exact same length as `AnyKeyframeGroup`),
   /// casts them to the expected type, and combined them into the final resulting keyframe.
+  ///
+  /// `requiresManualInterpolation` determines whether the keyframes must be computed using `Keyframes.manuallyInterpolated`,
+  /// which interpolates the value at each frame, or if the keyframes can simply be combined.
   private static func combined<CombinedResult>(
     _ allGroups: [AnyKeyframeGroup],
+    requiresManualInterpolation: Bool,
     makeCombinedResult: ([Any]) throws -> CombinedResult?)
     rethrows
     -> KeyframeGroup<CombinedResult>
@@ -155,6 +215,7 @@ enum Keyframes {
     let animatingKeyframes = untypedGroups.filter { $0.keyframes.count > 1 }
 
     guard
+      !requiresManualInterpolation,
       !allGroups.isEmpty,
       animatingKeyframes.allSatisfy({ $0.hasSameTimingParameters(as: animatingKeyframes[0]) })
     else {
@@ -222,7 +283,7 @@ enum Keyframes {
 extension KeyframeGroup {
   /// Whether or not all of the keyframes in this `KeyframeGroup` have the same
   /// timing parameters as the corresponding keyframe in the other given `KeyframeGroup`
-  func hasSameTimingParameters<T>(as other: KeyframeGroup<T>) -> Bool {
+  func hasSameTimingParameters<U>(as other: KeyframeGroup<U>) -> Bool {
     guard keyframes.count == other.keyframes.count else {
       return false
     }
@@ -236,7 +297,7 @@ extension KeyframeGroup {
 extension Keyframe {
   /// Whether or not this keyframe has the same timing parameters as the given keyframe,
   /// excluding `spatialInTangent` and `spatialOutTangent`.
-  fileprivate func hasSameTimingParameters<T>(as other: Keyframe<T>) -> Bool {
+  fileprivate func hasSameTimingParameters<U>(as other: Keyframe<U>) -> Bool {
     time == other.time
       && isHold == other.isHold
       && inTangent == other.inTangent