lottie-ios 3.2.3 → 3.4.0

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

@@ -0,0 +1,53 @@
+// Created by Cal Stephens on 1/28/22.
+// Copyright © 2022 Airbnb Inc. All rights reserved.
+
+import QuartzCore
+
+extension CAShapeLayer {
+  /// Adds animations for the given `CombinedShapeItem` to this `CALayer`
+  @nonobjc
+  func addAnimations(
+    for combinedShapes: CombinedShapeItem,
+    context: LayerAnimationContext,
+    pathMultiplier: PathMultiplier)
+    throws
+  {
+    try addAnimation(
+      for: .path,
+      keyframes: combinedShapes.shapes.keyframes,
+      value: { paths in
+        let combinedPath = CGMutablePath()
+        for path in paths {
+          combinedPath.addPath(path.cgPath().duplicated(times: pathMultiplier))
+        }
+        return combinedPath
+      },
+      context: context)
+  }
+}
+
+// MARK: - CombinedShapeItem
+
+/// A custom `ShapeItem` subclass that combines multiple `Shape`s into a single `KeyframeGroup`
+final class CombinedShapeItem: ShapeItem {
+
+  // MARK: Lifecycle
+
+  init(shapes: KeyframeGroup<[BezierPath]>, name: String) {
+    self.shapes = shapes
+    super.init(name: name, type: .shape, hidden: false)
+  }
+
+  required init(from _: Decoder) throws {
+    fatalError("init(from:) has not been implemented")
+  }
+
+  required init(dictionary _: [String: Any]) throws {
+    fatalError("init(dictionary:) has not been implemented")
+  }
+
+  // MARK: Internal
+
+  let shapes: KeyframeGroup<[BezierPath]>
+
+}

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

@@ -0,0 +1,41 @@
+// Created by Cal Stephens on 12/21/21.
+// Copyright © 2021 Airbnb Inc. All rights reserved.
+
+import QuartzCore
+
+extension CAShapeLayer {
+  /// Adds animations for the given `BezierPath` keyframes to this `CALayer`
+  @nonobjc
+  func addAnimations(
+    for customPath: KeyframeGroup<BezierPath>,
+    context: LayerAnimationContext,
+    pathMultiplier: PathMultiplier = 1,
+    transformPath: (CGPath) -> CGPath = { $0 })
+    throws
+  {
+    try addAnimation(
+      for: .path,
+      keyframes: customPath.keyframes,
+      value: { pathKeyframe in
+        transformPath(pathKeyframe.cgPath().duplicated(times: pathMultiplier))
+      },
+      context: context)
+  }
+}
+
+extension CGPath {
+  /// Duplicates this `CGPath` so that it is repeated the given number of times
+  func duplicated(times: Int) -> CGPath {
+    if times <= 1 {
+      return self
+    }
+
+    let cgPath = CGMutablePath()
+
+    for _ in 0..<times {
+      cgPath.addPath(self)
+    }
+
+    return cgPath
+  }
+}

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

@@ -0,0 +1,28 @@
+// Created by Cal Stephens on 12/21/21.
+// Copyright © 2021 Airbnb Inc. All rights reserved.
+
+import QuartzCore
+
+extension CAShapeLayer {
+  /// Adds animations for the given `Ellipse` to this `CALayer`
+  @nonobjc
+  func addAnimations(
+    for ellipse: Ellipse,
+    context: LayerAnimationContext,
+    pathMultiplier: PathMultiplier)
+    throws
+  {
+    try addAnimation(
+      for: .path,
+      keyframes: ellipse.size.keyframes,
+      value: { sizeKeyframe in
+        BezierPath.ellipse(
+          size: sizeKeyframe.sizeValue,
+          center: try ellipse.position.exactlyOneKeyframe(context: context, description: "ellipse position").value.pointValue,
+          direction: ellipse.direction)
+          .cgPath()
+          .duplicated(times: pathMultiplier)
+      },
+      context: context)
+  }
+}

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

@@ -0,0 +1,167 @@
+// Created by Cal Stephens on 1/7/22.
+// Copyright © 2022 Airbnb Inc. All rights reserved.
+
+import QuartzCore
+
+// MARK: - GradientShapeItem
+
+/// A `ShapeItem` that represents a gradient
+protocol GradientShapeItem: OpacityAnimationModel {
+  var startPoint: KeyframeGroup<Vector3D> { get }
+  var endPoint: KeyframeGroup<Vector3D> { get }
+  var gradientType: GradientType { get }
+  var numberOfColors: Int { get }
+  var colors: KeyframeGroup<[Double]> { get }
+}
+
+// MARK: - GradientFill + GradientShapeItem
+
+extension GradientFill: GradientShapeItem { }
+
+// MARK: - GradientStroke + GradientShapeItem
+
+extension GradientStroke: GradientShapeItem { }
+
+// MARK: - GradientRenderLayer + GradientShapeItem
+
+extension GradientRenderLayer {
+
+  // MARK: Internal
+
+  /// Adds gradient-related animations to this layer, from the given `GradientFill`
+  func addGradientAnimations(for gradient: GradientShapeItem, context: LayerAnimationContext) throws {
+    // We have to set `colors` to a non-nil value with some valid number of colors
+    // for the color animation below to have any effect
+    colors = .init(
+      repeating: CGColor.rgb(0, 0, 0),
+      count: gradient.numberOfColors)
+
+    try addAnimation(
+      for: .colors,
+      keyframes: gradient.colors.keyframes,
+      value: { colorComponents in
+        try gradient.colorConfiguration(from: colorComponents, context: context).map { $0.color }
+      },
+      context: context)
+
+    try addAnimation(
+      for: .locations,
+      keyframes: gradient.colors.keyframes,
+      value: { colorComponents in
+        try gradient.colorConfiguration(from: colorComponents, context: context).map { $0.location }
+      },
+      context: context)
+
+    try addOpacityAnimation(for: gradient, context: context)
+
+    switch gradient.gradientType {
+    case .linear:
+      try addLinearGradientAnimations(for: gradient, context: context)
+    case .radial:
+      try addRadialGradientAnimations(for: gradient, context: context)
+    case .none:
+      break
+    }
+  }
+
+  // MARK: Private
+
+  private func addLinearGradientAnimations(
+    for gradient: GradientShapeItem,
+    context: LayerAnimationContext)
+    throws
+  {
+    type = .axial
+
+    try addAnimation(
+      for: .startPoint,
+      keyframes: gradient.startPoint.keyframes,
+      value: { absoluteStartPoint in
+        percentBasedPointInBounds(from: absoluteStartPoint.pointValue)
+      },
+      context: context)
+
+    try addAnimation(
+      for: .endPoint,
+      keyframes: gradient.endPoint.keyframes,
+      value: { absoluteEndPoint in
+        percentBasedPointInBounds(from: absoluteEndPoint.pointValue)
+      },
+      context: context)
+  }
+
+  private func addRadialGradientAnimations(for gradient: GradientShapeItem, context: LayerAnimationContext) throws {
+    type = .radial
+
+    // To draw the correct gradients, we have to derive a custom `endPoint`
+    // relative to the `startPoint` value. Since calculating the `endPoint`
+    // at any given time requires knowing the current `startPoint`,
+    // we can't allow them to animate separately.
+    let absoluteStartPoint = try gradient.startPoint
+      .exactlyOneKeyframe(context: context, description: "gradient startPoint").value.pointValue
+
+    let absoluteEndPoint = try gradient.endPoint
+      .exactlyOneKeyframe(context: context, description: "gradient endPoint").value.pointValue
+
+    startPoint = percentBasedPointInBounds(from: absoluteStartPoint)
+
+    let radius = absoluteStartPoint.distanceTo(absoluteEndPoint)
+    endPoint = percentBasedPointInBounds(
+      from: CGPoint(
+        x: absoluteStartPoint.x + radius,
+        y: absoluteStartPoint.y + radius))
+  }
+}
+
+extension GradientShapeItem {
+  /// Converts the compact `[Double]` color components representation
+  /// into an array of `CGColor`s and the location of those colors within the gradient.
+  ///  - The color components array is a repeating list of `[location, red, green, blue]` values
+  ///    for each color in the gradient, followed by an optional repeating list of
+  ///    `[location, alpha]` values that control the colors' alpha values.
+  fileprivate func colorConfiguration(
+    from colorComponents: [Double],
+    context: LayerAnimationContext) throws
+    -> [(color: CGColor, location: CGFloat)]
+  {
+    precondition(
+      colorComponents.count >= numberOfColors * 4,
+      "Each color must have RGB components and a location component")
+
+    var cgColors = [(color: CGColor, location: CGFloat)]()
+
+    // Each group of four `Double` values represents a single `CGColor`,
+    // and its relative location within the gradient.
+    for colorIndex in 0..<numberOfColors {
+      let colorStartIndex = colorIndex * 4
+
+      let colorLocation = CGFloat(colorComponents[colorStartIndex])
+
+      // Alpha values aren't stored contiguously with the RGB color components,
+      // but are instead optionally listed at the end of the array
+      var alpha = 1.0
+      let alphaIndex = (numberOfColors * 4) + (colorIndex * 2)
+      if alphaIndex < colorComponents.count {
+        let alphaLocation = CGFloat(colorComponents[alphaIndex])
+        if alphaLocation == colorLocation {
+          alpha = colorComponents[alphaIndex + 1]
+        } else {
+          try context.logCompatibilityIssue("""
+            The Core Animation rendering engine currently expects gradient colors and alpha values
+            to be in the same order, with the same color stops / locations.
+            """)
+        }
+      }
+
+      let color = CGColor.rgba(
+        CGFloat(colorComponents[colorStartIndex + 1]),
+        CGFloat(colorComponents[colorStartIndex + 2]),
+        CGFloat(colorComponents[colorStartIndex + 3]),
+        CGFloat(alpha))
+
+      cgColors.append((color, colorLocation))
+    }
+
+    return cgColors
+  }
+}

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

@@ -0,0 +1,229 @@
+// Created by Cal Stephens on 1/11/22.
+// Copyright © 2022 Airbnb Inc. All rights reserved.
+
+import QuartzCore
+
+// MARK: - LayerProperty
+
+/// A strongly typed value that can be used as the `keyPath` of a `CAAnimation`
+///
+/// Supported key paths and their expected value types are described
+/// at https://developer.apple.com/library/archive/documentation/Cocoa/Conceptual/CoreAnimation_guide/AnimatableProperties/AnimatableProperties.html#//apple_ref/doc/uid/TP40004514-CH11-SW1
+/// and https://developer.apple.com/library/archive/documentation/Cocoa/Conceptual/CoreAnimation_guide/Key-ValueCodingExtensions/Key-ValueCodingExtensions.html
+struct LayerProperty<ValueRepresentation: Equatable> {
+  /// The `CALayer` KVC key path that this value should be assigned to
+  let caLayerKeypath: String
+
+  /// The default value of this property on a `CALayer`
+  ///  - If the keyframe values are just equal to the default value,
+  ///    then we can improve performance a bit by just not creating
+  ///    a CAAnimation (since it would be redundant).
+  let defaultValue: ValueRepresentation?
+
+  /// A description of how this property can be customized dynamically
+  /// at runtime using `AnimationView.setValueProvider(_:keypath:)`
+  let customizableProperty: CustomizableProperty<ValueRepresentation>?
+}
+
+// MARK: - CustomizableProperty
+
+/// A description of how a `CALayer` property can be customized dynamically
+/// at runtime using `AnimationView.setValueProvider(_:keypath:)`
+struct CustomizableProperty<ValueRepresentation> {
+  /// The name that `AnimationKeypath`s can use to refer to this property
+  ///  - When building an animation for this property that will be applied
+  ///    to a specific layer, this `name` is appended to the end of that
+  ///    layer's `AnimationKeypath`. The combined keypath is used to query
+  ///    the `ValueProviderStore`.
+  let name: [PropertyName]
+
+  /// 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?
+}
+
+// MARK: - PropertyName
+
+/// The name of a customizable property that can be used in an `AnimationKeypath`
+///  - These values should be shared between the two rendering engines,
+///    since they form the public API of the `AnimationKeypath` system.
+enum PropertyName: String {
+  case color = "Color"
+}
+
+// MARK: CALayer properties
+
+extension LayerProperty {
+  static var position: LayerProperty<CGPoint> {
+    .init(
+      caLayerKeypath: "transform.translation",
+      defaultValue: CGPoint(x: 0, y: 0),
+      customizableProperty: nil /* currently unsupported */)
+  }
+
+  static var positionX: LayerProperty<CGFloat> {
+    .init(
+      caLayerKeypath: "transform.translation.x",
+      defaultValue: 0,
+      customizableProperty: nil /* currently unsupported */)
+  }
+
+  static var positionY: LayerProperty<CGFloat> {
+    .init(
+      caLayerKeypath: "transform.translation.y",
+      defaultValue: 0,
+      customizableProperty: nil /* currently unsupported */)
+  }
+
+  static var scale: LayerProperty<CGFloat> {
+    .init(
+      caLayerKeypath: "transform.scale",
+      defaultValue: 1,
+      customizableProperty: nil /* currently unsupported */)
+  }
+
+  static var scaleX: LayerProperty<CGFloat> {
+    .init(
+      caLayerKeypath: "transform.scale.x",
+      defaultValue: 1,
+      customizableProperty: nil /* currently unsupported */)
+  }
+
+  static var scaleY: LayerProperty<CGFloat> {
+    .init(
+      caLayerKeypath: "transform.scale.y",
+      defaultValue: 1,
+      customizableProperty: nil /* currently unsupported */)
+  }
+
+  static var rotation: LayerProperty<CGFloat> {
+    .init(
+      caLayerKeypath: "transform.rotation",
+      defaultValue: 0,
+      customizableProperty: nil /* currently unsupported */)
+  }
+
+  static var rotationY: LayerProperty<CGFloat> {
+    .init(
+      caLayerKeypath: "transform.rotation.y",
+      defaultValue: 0,
+      customizableProperty: nil /* currently unsupported */)
+  }
+
+  static var anchorPoint: LayerProperty<CGPoint> {
+    .init(
+      caLayerKeypath: #keyPath(CALayer.anchorPoint),
+      // This is intentionally not `GGPoint(x: 0.5, y: 0.5)` (the actual default)
+      // to opt `anchorPoint` out of the KVC `setValue` flow, which causes issues.
+      defaultValue: nil,
+      customizableProperty: nil /* currently unsupported */)
+  }
+
+  static var opacity: LayerProperty<CGFloat> {
+    .init(
+      caLayerKeypath: #keyPath(CALayer.opacity),
+      defaultValue: 1,
+      customizableProperty: nil /* currently unsupported */)
+  }
+}
+
+// MARK: CAShapeLayer properties
+
+extension LayerProperty {
+  static var path: LayerProperty<CGPath> {
+    .init(
+      caLayerKeypath: #keyPath(CAShapeLayer.path),
+      defaultValue: nil,
+      customizableProperty: nil /* currently unsupported */)
+  }
+
+  static var fillColor: LayerProperty<CGColor> {
+    .init(
+      caLayerKeypath: #keyPath(CAShapeLayer.fillColor),
+      defaultValue: nil,
+      customizableProperty: .color)
+  }
+
+  static var lineWidth: LayerProperty<CGFloat> {
+    .init(
+      caLayerKeypath: #keyPath(CAShapeLayer.lineWidth),
+      defaultValue: 1,
+      customizableProperty: nil /* currently unsupported */)
+  }
+
+  static var lineDashPhase: LayerProperty<CGFloat> {
+    .init(
+      caLayerKeypath: #keyPath(CAShapeLayer.lineDashPhase),
+      defaultValue: 0,
+      customizableProperty: nil /* currently unsupported */)
+  }
+
+  static var strokeColor: LayerProperty<CGColor> {
+    .init(
+      caLayerKeypath: #keyPath(CAShapeLayer.strokeColor),
+      defaultValue: nil,
+      customizableProperty: .color)
+  }
+
+  static var strokeStart: LayerProperty<CGFloat> {
+    .init(
+      caLayerKeypath: #keyPath(CAShapeLayer.strokeStart),
+      defaultValue: 0,
+      customizableProperty: nil /* currently unsupported */)
+  }
+
+  static var strokeEnd: LayerProperty<CGFloat> {
+    .init(
+      caLayerKeypath: #keyPath(CAShapeLayer.strokeEnd),
+      defaultValue: 1,
+      customizableProperty: nil /* currently unsupported */)
+  }
+}
+
+// MARK: CAGradientLayer properties
+
+extension LayerProperty {
+  static var colors: LayerProperty<[CGColor]> {
+    .init(
+      caLayerKeypath: #keyPath(CAGradientLayer.colors),
+      defaultValue: nil,
+      customizableProperty: nil /* currently unsupported */)
+  }
+
+  static var locations: LayerProperty<[CGFloat]> {
+    .init(
+      caLayerKeypath: #keyPath(CAGradientLayer.locations),
+      defaultValue: nil,
+      customizableProperty: nil /* currently unsupported */)
+  }
+
+  static var startPoint: LayerProperty<CGPoint> {
+    .init(
+      caLayerKeypath: #keyPath(CAGradientLayer.startPoint),
+      defaultValue: nil,
+      customizableProperty: nil /* currently unsupported */)
+  }
+
+  static var endPoint: LayerProperty<CGPoint> {
+    .init(
+      caLayerKeypath: #keyPath(CAGradientLayer.endPoint),
+      defaultValue: nil,
+      customizableProperty: nil /* currently unsupported */)
+  }
+}
+
+// MARK: - CustomizableProperty types
+
+extension CustomizableProperty {
+  static var color: CustomizableProperty<CGColor> {
+    .init(
+      name: [.color],
+      conversion: { typeErasedValue in
+        guard let color = typeErasedValue as? Color else {
+          return nil
+        }
+
+        return .rgba(CGFloat(color.r), CGFloat(color.g), CGFloat(color.b), CGFloat(color.a))
+      })
+  }
+}

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

@@ -0,0 +1,52 @@
+// Created by Cal Stephens on 5/17/22.
+// Copyright © 2022 Airbnb Inc. All rights reserved.
+
+import QuartzCore
+
+// MARK: - OpacityAnimationModel
+
+protocol OpacityAnimationModel {
+  /// The opacity animation to apply to a `CALayer`
+  var opacity: KeyframeGroup<Vector1D> { get }
+}
+
+// MARK: - Transform + OpacityAnimationModel
+
+extension Transform: OpacityAnimationModel { }
+
+// MARK: - ShapeTransform + OpacityAnimationModel
+
+extension ShapeTransform: OpacityAnimationModel { }
+
+// MARK: - Fill + OpacityAnimationModel
+
+extension Fill: OpacityAnimationModel { }
+
+// MARK: - GradientFill + OpacityAnimationModel
+
+extension GradientFill: OpacityAnimationModel { }
+
+// MARK: - Stroke + OpacityAnimationModel
+
+extension Stroke: OpacityAnimationModel { }
+
+// MARK: - GradientStroke + OpacityAnimationModel
+
+extension GradientStroke: OpacityAnimationModel { }
+
+extension CALayer {
+  /// Adds the opacity animation from the given `OpacityAnimationModel` to this layer
+  @nonobjc
+  func addOpacityAnimation(for opacity: OpacityAnimationModel, context: LayerAnimationContext) throws {
+    try addAnimation(
+      for: .opacity,
+      keyframes: opacity.opacity.keyframes,
+      value: {
+        // Lottie animation files express opacity as a numerical percentage value
+        // (e.g. 0%, 50%, 100%) so we divide by 100 to get the decimal values
+        // expected by Core Animation (e.g. 0.0, 0.5, 1.0).
+        $0.cgFloatValue / 100
+      },
+      context: context)
+  }
+}

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

@@ -0,0 +1,31 @@
+// Created by Cal Stephens on 12/21/21.
+// Copyright © 2021 Airbnb Inc. All rights reserved.
+
+import QuartzCore
+
+extension CAShapeLayer {
+  /// Adds animations for the given `Rectangle` to this `CALayer`
+  @nonobjc
+  func addAnimations(
+    for rectangle: Rectangle,
+    context: LayerAnimationContext,
+    pathMultiplier: PathMultiplier)
+    throws
+  {
+    try addAnimation(
+      for: .path,
+      keyframes: rectangle.size.keyframes,
+      value: { sizeKeyframe in
+        BezierPath.rectangle(
+          position: try rectangle.position
+            .exactlyOneKeyframe(context: context, description: "rectangle position").value.pointValue,
+          size: sizeKeyframe.sizeValue,
+          cornerRadius: try rectangle.cornerRadius
+            .exactlyOneKeyframe(context: context, description: "rectangle cornerRadius").value.cgFloatValue,
+          direction: rectangle.direction)
+          .cgPath()
+          .duplicated(times: pathMultiplier)
+      },
+      context: context)
+  }
+}