lottie-ios 4.2.0 → 4.3.0

package/Sources/Public/DotLottie/DotLottieFileHelpers.swift

@@ -20,6 +20,10 @@ extension DotLottieFile {
       dotLottieCache: DotLottieCacheProvider? = DotLottieCache.sharedCache)
       -> Result<DotLottieFile, Error>
     {
+      LottieLogger.shared.assert(
+        !Thread.isMainThread,
+        "`DotLottieFile.SynchronouslyBlockingCurrentThread` methods shouldn't be called on the main thread.")
+
       /// Check cache for lottie
       if
         let dotLottieCache = dotLottieCache,
@@ -55,6 +59,10 @@ extension DotLottieFile {
       dotLottieCache: DotLottieCacheProvider? = DotLottieCache.sharedCache)
       -> Result<DotLottieFile, Error>
     {
+      LottieLogger.shared.assert(
+        !Thread.isMainThread,
+        "`DotLottieFile.SynchronouslyBlockingCurrentThread` methods shouldn't be called on the main thread.")
+
       /// Create a cache key for the lottie.
       let cacheKey = bundle.bundlePath + (subdirectory ?? "") + "/" + name
 
@@ -78,6 +86,30 @@ extension DotLottieFile {
         return .failure(error)
       }
     }
+
+    /// Loads an DotLottie from a data synchronously. Returns a `Result<DotLottieFile, Error>`
+    ///
+    /// Please use the asynchronous methods whenever possible. This operation will block the Thread it is running in.
+    ///
+    /// - Parameters:
+    ///   - data: The data(`Foundation.Data`) object to load DotLottie from
+    ///   - filename: The name of the lottie file without the lottie extension. eg. "StarAnimation"
+    public static func loadedFrom(
+      data: Data,
+      filename: String)
+      -> Result<DotLottieFile, Error>
+    {
+      LottieLogger.shared.assert(
+        !Thread.isMainThread,
+        "`DotLottieFile.SynchronouslyBlockingCurrentThread` methods shouldn't be called on the main thread.")
+
+      do {
+        let dotLottieFile = try DotLottieFile(data: data, filename: filename)
+        return .success(dotLottieFile)
+      } catch {
+        return .failure(error)
+      }
+    }
   }
 
   /// Loads a DotLottie model from a bundle by its name. Returns `nil` if a file is not found.
@@ -289,4 +321,51 @@ extension DotLottieFile {
     }
   }
 
+  /// Loads an DotLottie from a data asynchronously.
+  ///
+  /// - Parameters:
+  ///   - data: The data(`Foundation.Data`) object to load DotLottie from
+  ///   - filename: The name of the lottie file without the lottie extension. eg. "StarAnimation"
+  ///   - dispatchQueue: A dispatch queue used to load animations. Defaults to `DispatchQueue.global()`. Optional.
+  ///   - handleResult: A closure to be called when the file has loaded.
+  public static func loadedFrom(
+    data: Data,
+    filename: String,
+    dispatchQueue: DispatchQueue = .global(),
+    handleResult: @escaping (Result<DotLottieFile, Error>) -> Void)
+  {
+    dispatchQueue.async {
+      do {
+        let dotLottie = try DotLottieFile(data: data, filename: filename)
+        DispatchQueue.main.async {
+          handleResult(.success(dotLottie))
+        }
+      } catch {
+        DispatchQueue.main.async {
+          handleResult(.failure(error))
+        }
+      }
+    }
+  }
+
+  /// Loads an DotLottie from a data asynchronously.
+  ///
+  /// - Parameters:
+  ///   - data: The data(`Foundation.Data`) object to load DotLottie from
+  ///   - filename: The name of the lottie file without the lottie extension. eg. "StarAnimation"
+  ///   - dispatchQueue: A dispatch queue used to load animations. Defaults to `DispatchQueue.global()`. Optional.
+  @available(iOS 13.0, macOS 10.15, tvOS 13.0, *)
+  public static func loadedFrom(
+    data: Data,
+    filename: String,
+    dispatchQueue: DispatchQueue = .global())
+    async throws -> DotLottieFile
+  {
+    try await withCheckedThrowingContinuation { continuation in
+      loadedFrom(data: data, filename: filename, dispatchQueue: dispatchQueue) { result in
+        continuation.resume(with: result)
+      }
+    }
+  }
+
 }

package/Sources/Public/DynamicProperties/AnimationKeypath.swift

@@ -29,6 +29,8 @@ import Foundation
 /// Represents the color node for every Stroke named "Stroke 1" in the animation.
 public struct AnimationKeypath: Hashable, ExpressibleByStringLiteral {
 
+  // MARK: Lifecycle
+
   /// Creates a keypath from a dot-separated string. The string is separated by "."
   public init(keypath: String) {
     keys = keypath.components(separatedBy: ".")
@@ -44,6 +46,14 @@ public struct AnimationKeypath: Hashable, ExpressibleByStringLiteral {
     self.keys = keys
   }
 
-  var keys: [String]
+  // MARK: Public
+
+  /// The dot-separated key values that represent this keypath.
+  public internal(set) var keys: [String]
+
+  /// The `String` representation of this keypath
+  public var string: String {
+    keys.joined(separator: ".")
+  }
 
 }

package/Sources/Public/DynamicProperties/ValueProviders/ColorValueProvider.swift

@@ -8,6 +8,8 @@
 import CoreGraphics
 import Foundation
 
+// MARK: - ColorValueProvider
+
 /// A `ValueProvider` that returns a CGColor Value
 public final class ColorValueProvider: ValueProvider {
 
@@ -18,6 +20,7 @@ public final class ColorValueProvider: ValueProvider {
     self.block = block
     color = LottieColor(r: 0, g: 0, b: 0, a: 1)
     keyframes = nil
+    identity = UUID()
   }
 
   /// Initializes with a single color.
@@ -26,6 +29,7 @@ public final class ColorValueProvider: ValueProvider {
     block = nil
     keyframes = nil
     hasUpdate = true
+    identity = color
   }
 
   /// Initializes with multiple colors, with timing information
@@ -34,6 +38,7 @@ public final class ColorValueProvider: ValueProvider {
     color = LottieColor(r: 0, g: 0, b: 0, a: 1)
     block = nil
     hasUpdate = true
+    identity = keyframes
   }
 
   // MARK: Public
@@ -81,4 +86,13 @@ public final class ColorValueProvider: ValueProvider {
 
   private var block: ColorValueBlock?
   private var keyframes: [Keyframe<LottieColor>]?
+  private var identity: AnyHashable
+}
+
+// MARK: Equatable
+
+extension ColorValueProvider: Equatable {
+  public static func ==(_ lhs: ColorValueProvider, _ rhs: ColorValueProvider) -> Bool {
+    lhs.identity == rhs.identity
+  }
 }

package/Sources/Public/DynamicProperties/ValueProviders/FloatValueProvider.swift

@@ -8,6 +8,8 @@
 import CoreGraphics
 import Foundation
 
+// MARK: - FloatValueProvider
+
 /// A `ValueProvider` that returns a CGFloat Value
 public final class FloatValueProvider: ValueProvider {
 
@@ -17,6 +19,7 @@ public final class FloatValueProvider: ValueProvider {
   public init(block: @escaping CGFloatValueBlock) {
     self.block = block
     float = 0
+    identity = UUID()
   }
 
   /// Initializes with a single float.
@@ -24,6 +27,7 @@ public final class FloatValueProvider: ValueProvider {
     self.float = float
     block = nil
     hasUpdate = true
+    identity = float
   }
 
   // MARK: Public
@@ -67,4 +71,13 @@ public final class FloatValueProvider: ValueProvider {
   private var hasUpdate = true
 
   private var block: CGFloatValueBlock?
+  private var identity: AnyHashable
+}
+
+// MARK: Equatable
+
+extension FloatValueProvider: Equatable {
+  public static func ==(_ lhs: FloatValueProvider, _ rhs: FloatValueProvider) -> Bool {
+    lhs.identity == rhs.identity
+  }
 }

package/Sources/Public/DynamicProperties/ValueProviders/GradientValueProvider.swift

@@ -8,6 +8,8 @@
 import CoreGraphics
 import Foundation
 
+// MARK: - GradientValueProvider
+
 /// A `ValueProvider` that returns a Gradient Color Value.
 public final class GradientValueProvider: ValueProvider {
 
@@ -22,6 +24,7 @@ public final class GradientValueProvider: ValueProvider {
     locationsBlock = locations
     colors = []
     self.locations = []
+    identity = UUID()
   }
 
   /// Initializes with an array of colors.
@@ -31,6 +34,7 @@ public final class GradientValueProvider: ValueProvider {
   {
     self.colors = colors
     self.locations = locations
+    identity = [AnyHashable(colors), AnyHashable(locations)]
     updateValueArray()
     hasUpdate = true
   }
@@ -65,16 +69,18 @@ public final class GradientValueProvider: ValueProvider {
   }
 
   public var storage: ValueProviderStorage<[Double]> {
-    .closure { [self] frame in
-      hasUpdate = false
+    if let block = block {
+      return .closure { [self] frame in
+        hasUpdate = false
 
-      if let block = block {
         let newColors = block(frame)
         let newLocations = locationsBlock?(frame) ?? []
         value = value(from: newColors, locations: newLocations)
-      }
 
-      return value
+        return value
+      }
+    } else {
+      return .singleValue(value)
     }
   }
 
@@ -93,6 +99,8 @@ public final class GradientValueProvider: ValueProvider {
   private var locationsBlock: ColorLocationsBlock?
   private var value: [Double] = []
 
+  private let identity: AnyHashable
+
   private func value(from colors: [LottieColor], locations: [Double]) -> [Double] {
     var colorValues = [Double]()
     var alphaValues = [Double]()
@@ -120,4 +128,13 @@ public final class GradientValueProvider: ValueProvider {
   private func updateValueArray() {
     value = value(from: colors, locations: locations)
   }
+
+}
+
+// MARK: Equatable
+
+extension GradientValueProvider: Equatable {
+  public static func ==(_ lhs: GradientValueProvider, _ rhs: GradientValueProvider) -> Bool {
+    lhs.identity == rhs.identity
+  }
 }

package/Sources/Public/DynamicProperties/ValueProviders/PointValueProvider.swift

@@ -7,6 +7,9 @@
 
 import CoreGraphics
 import Foundation
+
+// MARK: - PointValueProvider
+
 /// A `ValueProvider` that returns a CGPoint Value
 public final class PointValueProvider: ValueProvider {
 
@@ -16,6 +19,7 @@ public final class PointValueProvider: ValueProvider {
   public init(block: @escaping PointValueBlock) {
     self.block = block
     point = .zero
+    identity = UUID()
   }
 
   /// Initializes with a single point.
@@ -23,6 +27,7 @@ public final class PointValueProvider: ValueProvider {
     self.point = point
     block = nil
     hasUpdate = true
+    identity = [point.x, point.y]
   }
 
   // MARK: Public
@@ -66,4 +71,13 @@ public final class PointValueProvider: ValueProvider {
   private var hasUpdate = true
 
   private var block: PointValueBlock?
+  private let identity: AnyHashable
+}
+
+// MARK: Equatable
+
+extension PointValueProvider: Equatable {
+  public static func ==(_ lhs: PointValueProvider, _ rhs: PointValueProvider) -> Bool {
+    lhs.identity == rhs.identity
+  }
 }

package/Sources/Public/DynamicProperties/ValueProviders/SizeValueProvider.swift

@@ -8,6 +8,8 @@
 import CoreGraphics
 import Foundation
 
+// MARK: - SizeValueProvider
+
 /// A `ValueProvider` that returns a CGSize Value
 public final class SizeValueProvider: ValueProvider {
 
@@ -17,6 +19,7 @@ public final class SizeValueProvider: ValueProvider {
   public init(block: @escaping SizeValueBlock) {
     self.block = block
     size = .zero
+    identity = UUID()
   }
 
   /// Initializes with a single size.
@@ -24,6 +27,7 @@ public final class SizeValueProvider: ValueProvider {
     self.size = size
     block = nil
     hasUpdate = true
+    identity = [size.width, size.height]
   }
 
   // MARK: Public
@@ -67,4 +71,13 @@ public final class SizeValueProvider: ValueProvider {
   private var hasUpdate = true
 
   private var block: SizeValueBlock?
+  private let identity: AnyHashable
+}
+
+// MARK: Equatable
+
+extension SizeValueProvider: Equatable {
+  public static func ==(_ lhs: SizeValueProvider, _ rhs: SizeValueProvider) -> Bool {
+    lhs.identity == rhs.identity
+  }
 }

package/Sources/Public/FontProvider/AnimationFontProvider.swift

@@ -33,3 +33,11 @@ public final class DefaultFontProvider: AnimationFontProvider {
     CTFontCreateWithName(family as CFString, size, nil)
   }
 }
+
+// MARK: Equatable
+
+extension DefaultFontProvider: Equatable {
+  public static func ==(_: DefaultFontProvider, _: DefaultFontProvider) -> Bool {
+    true
+  }
+}

package/Sources/Public/ImageProvider/AnimationImageProvider.swift

@@ -7,6 +7,9 @@
 
 import CoreGraphics
 import Foundation
+import QuartzCore
+
+// MARK: - AnimationImageProvider
 
 /// Image provider is a protocol that is used to supply images to `LottieAnimationView`.
 ///
@@ -17,5 +20,26 @@ import Foundation
 /// Additionally custom Image Providers can be made to load images from a URL,
 /// or to Cache images.
 public protocol AnimationImageProvider {
+
+  /// Whether or not the resulting image of this image provider can be cached by Lottie. Defaults to true.
+  /// If true, Lottie may internally cache the result of `imageForAsset`
+  var cacheEligible: Bool { get }
+
+  /// The image to display for the given `ImageAsset` defined in the `LottieAnimation` JSON file.
   func imageForAsset(asset: ImageAsset) -> CGImage?
+
+  /// Specifies how the layer's contents are positioned or scaled within its bounds for a given asset.
+  /// Defaults to `.resize`, which stretches the image to fill the layer.
+  func contentsGravity(for asset: ImageAsset) -> CALayerContentsGravity
+}
+
+extension AnimationImageProvider {
+  public var cacheEligible: Bool {
+    true
+  }
+
+  /// The default value is `.resize`, similar to that of `CALayer`.
+  public func contentsGravity(for _: ImageAsset) -> CALayerContentsGravity {
+    .resize
+  }
 }

package/Sources/Public/Keyframes/Keyframe.swift

@@ -1,6 +1,8 @@
 // Created by Cal Stephens on 1/24/22.
 // Copyright © 2022 Airbnb Inc. All rights reserved.
 
+import CoreFoundation
+
 // MARK: - Keyframe
 
 /// A keyframe with a single value, and timing information
@@ -90,3 +92,7 @@ extension Keyframe: Hashable where T: Hashable {
     hasher.combine(spatialOutTangent)
   }
 }
+
+// MARK: Sendable
+
+extension Keyframe: Sendable where T: Sendable { }

package/Sources/Public/Primitives/Vectors.swift

@@ -9,7 +9,7 @@ import Foundation
 
 // MARK: - LottieVector1D
 
-public struct LottieVector1D: Hashable {
+public struct LottieVector1D: Hashable, Sendable {
 
   public init(_ value: Double) {
     self.value = value
@@ -23,7 +23,7 @@ public struct LottieVector1D: Hashable {
 
 /// A three dimensional vector.
 /// These vectors are encoded and decoded from [Double]
-public struct LottieVector3D: Hashable {
+public struct LottieVector3D: Hashable, Sendable {
 
   public let x: Double
   public let y: Double

package/Sources/Public/TextProvider/AnimationTextProvider.swift

@@ -7,17 +7,52 @@
 
 import Foundation
 
-// MARK: - AnimationTextProvider
+// MARK: - AnimationKeypathTextProvider
 
-/// Text provider is a protocol that is used to supply text to `LottieAnimationView`.
-public protocol AnimationTextProvider: AnyObject {
+/// Protocol for providing dynamic text to for a Lottie animation.
+public protocol AnimationKeypathTextProvider: AnyObject {
+  /// The text to display for the given `AnimationKeypath`.
+  /// If `nil` is returned, continues using the existing default text value.
+  func text(for keypath: AnimationKeypath, sourceText: String) -> String?
+}
+
+// MARK: - AnimationKeypathTextProvider
+
+/// Legacy protocol for providing dynamic text for a Lottie animation.
+/// Instead prefer conforming to `AnimationKeypathTextProvider`.
+@available(*, deprecated, message: """
+  `AnimationKeypathTextProvider` has been deprecated and renamed to `LegacyAnimationTextProvider`. \
+  Instead, conform to `AnimationKeypathTextProvider` instead or conform to `LegacyAnimationTextProvider` explicitly.
+  """)
+public typealias AnimationTextProvider = LegacyAnimationTextProvider
+
+// MARK: - LegacyAnimationTextProvider
+
+/// Legacy protocol for providing dynamic text for a Lottie animation.
+/// Instead prefer conforming to `AnimationKeypathTextProvider`.
+public protocol LegacyAnimationTextProvider: AnimationKeypathTextProvider {
+  /// Legacy method to look up the text to display for the given keypath.
+  /// Instead, prefer implementing `AnimationKeypathTextProvider.`
+  /// The behavior of this method depends on the current rendering engine:
+  ///  - The Core Animation rendering engine always calls this method
+  ///    with the full keypath (e.g. `MY_LAYER.text_value`).
+  ///  - The Main Thread rendering engine always calls this method
+  ///    with the final component of the key path (e.g. just `text_value`).
   func textFor(keypathName: String, sourceText: String) -> String
 }
 
+extension LegacyAnimationTextProvider {
+  public func text(for _: AnimationKeypath, sourceText _: String) -> String? {
+    nil
+  }
+}
+
 // MARK: - DictionaryTextProvider
 
-/// Text provider that simply map values from dictionary
-public final class DictionaryTextProvider: AnimationTextProvider {
+/// Text provider that simply map values from dictionary.
+///  - The dictionary keys can either be the full layer keypath string (e.g. `MY_LAYER.text_value`)
+///    or simply the final path component of the keypath (e.g. `text_value`).
+public final class DictionaryTextProvider: AnimationKeypathTextProvider, LegacyAnimationTextProvider {
 
   // MARK: Lifecycle
 
@@ -27,6 +62,24 @@ public final class DictionaryTextProvider: AnimationTextProvider {
 
   // MARK: Public
 
+  public func text(for keypath: AnimationKeypath, sourceText: String) -> String? {
+    if let valueForFullKeypath = values[keypath.fullPath] {
+      return valueForFullKeypath
+    }
+
+    else if
+      let lastKeypathComponent = keypath.keys.last,
+      let valueForLastComponent = values[lastKeypathComponent]
+    {
+      return valueForLastComponent
+    }
+
+    else {
+      return sourceText
+    }
+  }
+
+  // Never called directly by Lottie, but we continue to implement this conformance for backwards compatibility.
   public func textFor(keypathName: String, sourceText: String) -> String {
     values[keypathName] ?? sourceText
   }
@@ -36,10 +89,18 @@ public final class DictionaryTextProvider: AnimationTextProvider {
   let values: [String: String]
 }
 
+// MARK: Equatable
+
+extension DictionaryTextProvider: Equatable {
+  public static func ==(_ lhs: DictionaryTextProvider, _ rhs: DictionaryTextProvider) -> Bool {
+    lhs.values == rhs.values
+  }
+}
+
 // MARK: - DefaultTextProvider
 
 /// Default text provider. Uses text in the animation file
-public final class DefaultTextProvider: AnimationTextProvider {
+public final class DefaultTextProvider: AnimationKeypathTextProvider, LegacyAnimationTextProvider {
 
   // MARK: Lifecycle
 
@@ -50,4 +111,16 @@ public final class DefaultTextProvider: AnimationTextProvider {
   public func textFor(keypathName _: String, sourceText: String) -> String {
     sourceText
   }
+
+  public func text(for _: AnimationKeypath, sourceText: String) -> String {
+    sourceText
+  }
+}
+
+// MARK: Equatable
+
+extension DefaultTextProvider: Equatable {
+  public static func ==(_: DefaultTextProvider, _: DefaultTextProvider) -> Bool {
+    true
+  }
 }

package/Sources/Public/iOS/AnimationSubview.swift

@@ -6,7 +6,7 @@
 //
 
 import Foundation
-#if os(iOS) || os(tvOS) || os(watchOS) || targetEnvironment(macCatalyst)
+#if canImport(UIKit)
 import UIKit
 
 /// A view that can be added to a keypath of an AnimationView

package/Sources/Public/iOS/BundleImageProvider.swift

@@ -7,7 +7,7 @@
 
 import CoreGraphics
 import Foundation
-#if os(iOS) || os(tvOS) || os(watchOS) || targetEnvironment(macCatalyst)
+#if canImport(UIKit)
 import UIKit
 
 /// An `AnimationImageProvider` that provides images by name from a specific bundle.
@@ -23,10 +23,12 @@ public class BundleImageProvider: AnimationImageProvider {
   ///
   /// - Parameter bundle: The bundle containing images for the provider.
   /// - Parameter searchPath: The subpath is a path within the bundle to search for image assets.
+  /// - Parameter contentsGravity: The contents gravity to use when rendering the image.
   ///
-  public init(bundle: Bundle, searchPath: String?) {
+  public init(bundle: Bundle, searchPath: String?, contentsGravity: CALayerContentsGravity = .resize) {
     self.bundle = bundle
     self.searchPath = searchPath
+    self.contentsGravity = contentsGravity
   }
 
   // MARK: Public
@@ -81,9 +83,21 @@ public class BundleImageProvider: AnimationImageProvider {
     return image.cgImage
   }
 
+  public func contentsGravity(for _: ImageAsset) -> CALayerContentsGravity {
+    contentsGravity
+  }
+
   // MARK: Internal
 
   let bundle: Bundle
   let searchPath: String?
+  let contentsGravity: CALayerContentsGravity
+}
+
+extension BundleImageProvider: Equatable {
+  public static func ==(_ lhs: BundleImageProvider, _ rhs: BundleImageProvider) -> Bool {
+    lhs.bundle == rhs.bundle
+      && lhs.searchPath == rhs.searchPath
+  }
 }
 #endif

package/Sources/Public/iOS/Compatibility/CompatibleAnimationView.swift

@@ -30,7 +30,7 @@ public final class CompatibleAnimation: NSObject {
 
   // MARK: Internal
 
-  internal var animation: LottieAnimation? {
+  var animation: LottieAnimation? {
     LottieAnimation.named(name, bundle: bundle, subdirectory: subdirectory)
   }
 
@@ -533,7 +533,7 @@ public final class CompatibleDictionaryTextProvider: NSObject {
 
   // MARK: Internal
 
-  internal var textProvider: AnimationTextProvider? {
+  var textProvider: AnimationKeypathTextProvider? {
     DictionaryTextProvider(values)
   }