lottie-ios 3.2.3 → 3.4.0

package/Sources/Public/Animation/AnimationViewInitializers.swift

@@ -0,0 +1,107 @@
+//
+//  AnimationViewInitializers.swift
+//  lottie-swift-iOS
+//
+//  Created by Brandon Withrow on 2/6/19.
+//
+
+import Foundation
+
+extension AnimationView {
+
+  // MARK: Lifecycle
+
+  /// Loads a Lottie animation from a JSON file in the supplied bundle.
+  ///
+  /// - Parameter name: The string name of the lottie animation with no file
+  /// extension provided.
+  /// - Parameter bundle: The bundle in which the animation is located.
+  /// Defaults to the Main bundle.
+  /// - Parameter imageProvider: An image provider for the animation's image data.
+  /// If none is supplied Lottie will search in the supplied bundle for images.
+  public convenience init(
+    name: String,
+    bundle: Bundle = Bundle.main,
+    imageProvider: AnimationImageProvider? = nil,
+    animationCache: AnimationCacheProvider? = LRUAnimationCache.sharedCache)
+  {
+    let animation = Animation.named(name, bundle: bundle, subdirectory: nil, animationCache: animationCache)
+    let provider = imageProvider ?? BundleImageProvider(bundle: bundle, searchPath: nil)
+    self.init(animation: animation, imageProvider: provider)
+  }
+
+  /// Loads a Lottie animation from a JSON file in a specific path on disk.
+  ///
+  /// - Parameter name: The absolute path of the Lottie Animation.
+  /// - Parameter imageProvider: An image provider for the animation's image data.
+  /// If none is supplied Lottie will search in the supplied filepath for images.
+  public convenience init(
+    filePath: String,
+    imageProvider: AnimationImageProvider? = nil,
+    animationCache: AnimationCacheProvider? = LRUAnimationCache.sharedCache)
+  {
+    let animation = Animation.filepath(filePath, animationCache: animationCache)
+    let provider = imageProvider ??
+      FilepathImageProvider(filepath: URL(fileURLWithPath: filePath).deletingLastPathComponent().path)
+    self.init(animation: animation, imageProvider: provider)
+  }
+
+  /// Loads a Lottie animation asynchronously from the URL
+  ///
+  /// - Parameter url: The url to load the animation from.
+  /// - Parameter imageProvider: An image provider for the animation's image data.
+  /// If none is supplied Lottie will search in the main bundle for images.
+  /// - Parameter closure: A closure to be called when the animation has loaded.
+  public convenience init(
+    url: URL,
+    imageProvider: AnimationImageProvider? = nil,
+    closure: @escaping AnimationView.DownloadClosure,
+    animationCache: AnimationCacheProvider? = LRUAnimationCache.sharedCache)
+  {
+
+    if let animationCache = animationCache, let animation = animationCache.animation(forKey: url.absoluteString) {
+      self.init(animation: animation, imageProvider: imageProvider)
+      closure(nil)
+    } else {
+
+      self.init(animation: nil, imageProvider: imageProvider)
+
+      Animation.loadedFrom(url: url, closure: { animation in
+        if let animation = animation {
+          self.animation = animation
+          closure(nil)
+        } else {
+          closure(LottieDownloadError.downloadFailed)
+        }
+      }, animationCache: animationCache)
+    }
+  }
+
+  /// Loads a Lottie animation from a JSON file located in the Asset catalog of the supplied bundle.
+  /// - Parameter name: The string name of the lottie animation in the asset catalog.
+  /// - Parameter bundle: The bundle in which the animation is located.
+  /// Defaults to the Main bundle.
+  /// - Parameter imageProvider: An image provider for the animation's image data.
+  /// If none is supplied Lottie will search in the supplied bundle for images.
+  public convenience init(
+    asset name: String,
+    bundle: Bundle = Bundle.main,
+    imageProvider: AnimationImageProvider? = nil,
+    animationCache: AnimationCacheProvider? = LRUAnimationCache.sharedCache)
+  {
+    let animation = Animation.asset(name, bundle: bundle, animationCache: animationCache)
+    let provider = imageProvider ?? BundleImageProvider(bundle: bundle, searchPath: nil)
+    self.init(animation: animation, imageProvider: provider)
+  }
+
+  // MARK: Public
+
+  public typealias DownloadClosure = (Error?) -> Void
+
+}
+
+// MARK: - LottieDownloadError
+
+enum LottieDownloadError: Error {
+  case downloadFailed
+}

package/Sources/Public/AnimationCache/AnimationCacheProvider.swift

@@ -0,0 +1,22 @@
+//
+//  AnimationCacheProvider.swift
+//  lottie-swift
+//
+//  Created by Brandon Withrow on 2/5/19.
+//
+
+import Foundation
+/// `AnimationCacheProvider` is a protocol that describes an Animation Cache.
+/// Animation Cache is used when loading `Animation` models. Using an Animation Cache
+/// can increase performance when loading an animation multiple times.
+///
+/// Lottie comes with a prebuilt LRU Animation Cache.
+public protocol AnimationCacheProvider {
+
+  func animation(forKey: String) -> Animation?
+
+  func setAnimation(_ animation: Animation, forKey: String)
+
+  func clearCache()
+
+}

package/{lottie-swift/src → Sources}/Public/AnimationCache/LRUAnimationCache.swift

@@ -7,28 +7,30 @@
 
 import Foundation
 
-/**
- An Animation Cache that will store animations up to `cacheSize`.
- 
- Once `cacheSize` is reached, the least recently used animation will be ejected.
- The default size of the cache is 100.
- */
+/// An Animation Cache that will store animations up to `cacheSize`.
+///
+/// Once `cacheSize` is reached, the least recently used animation will be ejected.
+/// The default size of the cache is 100.
 public class LRUAnimationCache: AnimationCacheProvider {
 
+  // MARK: Lifecycle
+
   public init() { }
-  
+
+  // MARK: Public
+
+  /// The global shared Cache.
+  public static let sharedCache = LRUAnimationCache()
+
+  /// The size of the cache.
+  public var cacheSize = 100
+
   /// Clears the Cache.
   public func clearCache() {
     cacheMap.removeAll()
     lruList.removeAll()
   }
-  
-  /// The global shared Cache.
-  public static let sharedCache = LRUAnimationCache()
-  
-  /// The size of the cache.
-  public var cacheSize: Int = 100
-  
+
   public func animation(forKey: String) -> Animation? {
     guard let animation = cacheMap[forKey] else {
       return nil
@@ -39,7 +41,7 @@ public class LRUAnimationCache: AnimationCacheProvider {
     }
     return animation
   }
-  
+
   public func setAnimation(_ animation: Animation, forKey: String) {
     cacheMap[forKey] = animation
     lruList.append(forKey)
@@ -50,8 +52,10 @@ public class LRUAnimationCache: AnimationCacheProvider {
       }
     }
   }
-  
-  fileprivate var cacheMap: [String : Animation] = [:]
+
+  // MARK: Fileprivate
+
+  fileprivate var cacheMap: [String: Animation] = [:]
   fileprivate var lruList: [String] = []
-  
+
 }

package/Sources/Public/DynamicProperties/AnimationKeypath.swift

@@ -0,0 +1,49 @@
+//
+//  AnimationKeypath.swift
+//  lottie-swift
+//
+//  Created by Brandon Withrow on 2/4/19.
+//
+
+import Foundation
+
+/// `AnimationKeypath` is an object that describes a keypath search for nodes in the
+/// animation JSON. `AnimationKeypath` matches views and properties inside of `AnimationView`
+/// to their backing `Animation` model by name.
+///
+/// A keypath can be used to set properties on an existing animation, or can be validated
+/// with an existing `Animation`.
+///
+/// `AnimationKeypath` can describe a specific object, or can use wildcards for fuzzy matching
+/// of objects. Acceptable wildcards are either "*" (star) or "**" (double star).
+/// Single star will search a single depth for the next object.
+/// Double star will search any depth.
+///
+/// Read More at https://airbnb.io/lottie/#/ios?id=dynamic-animation-properties
+///
+/// EG:
+/// @"Layer.Shape Group.Stroke 1.Color"
+/// Represents a specific color node on a specific stroke.
+///
+/// @"**.Stroke 1.Color"
+/// Represents the color node for every Stroke named "Stroke 1" in the animation.
+public struct AnimationKeypath: Hashable, ExpressibleByStringLiteral {
+
+  /// Creates a keypath from a dot-separated string. The string is separated by "."
+  public init(keypath: String) {
+    keys = keypath.components(separatedBy: ".")
+  }
+
+  /// Creates a keypath from a dot-separated string
+  public init(stringLiteral: String) {
+    self.init(keypath: stringLiteral)
+  }
+
+  /// Creates a keypath from a list of strings.
+  public init(keys: [String]) {
+    self.keys = keys
+  }
+
+  var keys: [String]
+
+}

package/Sources/Public/DynamicProperties/AnyValueProvider.swift

@@ -0,0 +1,132 @@
+//
+//  AnyValueProvider.swift
+//  lottie-swift
+//
+//  Created by Brandon Withrow on 1/30/19.
+//
+
+import CoreGraphics
+import Foundation
+
+// MARK: - AnyValueProvider
+
+/// `AnyValueProvider` is a protocol that return animation data for a property at a
+/// given time. Every frame an `AnimationView` queries all of its properties and asks
+/// if their ValueProvider has an update. If it does the AnimationView will read the
+/// property and update that portion of the animation.
+///
+/// Value Providers can be used to dynamically set animation properties at run time.
+public protocol AnyValueProvider {
+
+  /// The Type of the value provider
+  var valueType: Any.Type { get }
+
+  /// The type-erased storage for this Value Provider
+  var typeErasedStorage: AnyValueProviderStorage { get }
+
+  /// Asks the provider if it has an update for the given frame.
+  func hasUpdate(frame: AnimationFrameTime) -> Bool
+
+}
+
+extension AnyValueProvider {
+  /// Asks the provider to update the container with its value for the frame.
+  public func value(frame: AnimationFrameTime) -> Any {
+    typeErasedStorage.value(frame: frame)
+  }
+}
+
+// MARK: - ValueProvider
+
+/// A base protocol for strongly-typed Value Providers
+protocol ValueProvider: AnyValueProvider {
+  associatedtype Value: AnyInterpolatable
+
+  /// The strongly-typed storage for this Value Provider
+  var storage: ValueProviderStorage<Value> { get }
+}
+
+extension ValueProvider {
+  public var typeErasedStorage: AnyValueProviderStorage {
+    switch storage {
+    case .closure(let typedClosure):
+      return .closure(typedClosure)
+
+    case .singleValue(let typedValue):
+      return .singleValue(typedValue)
+
+    case .keyframes(let keyframes):
+      return .keyframes(
+        keyframes.map { keyframe in
+          keyframe.withValue(keyframe.value as Any)
+        },
+        interpolate: storage.value(frame:))
+    }
+  }
+}
+
+// MARK: - ValueProviderStorage
+
+/// The underlying storage of a `ValueProvider`
+public enum ValueProviderStorage<T: AnyInterpolatable> {
+  /// The value provider stores a single value that is used on all frames
+  case singleValue(T)
+
+  /// The value provider stores a group of keyframes
+  ///  - The main-thread rendering engine interpolates values in these keyframes
+  ///    using `T`'s `Interpolatable` implementation.
+  ///  - The Core Animation rendering engine constructs a `CAKeyframeAnimation`
+  ///    using these keyframes. The Core Animation render server performs
+  ///    the interpolation, without calling `T`'s `Interpolatable` implementation.
+  case keyframes([Keyframe<T>])
+
+  /// The value provider stores a closure that is invoked on every frame
+  ///  - This is only supported by the main-thread rendering engine
+  case closure((AnimationFrameTime) -> T)
+
+  // MARK: Internal
+
+  func value(frame: AnimationFrameTime) -> T {
+    switch self {
+    case .singleValue(let value):
+      return value
+
+    case .closure(let closure):
+      return closure(frame)
+
+    case .keyframes(let keyframes):
+      return KeyframeInterpolator(keyframes: ContiguousArray(keyframes)).storage.value(frame: frame)
+    }
+  }
+}
+
+// MARK: - AnyValueProviderStorage
+
+/// A type-erased representation of `ValueProviderStorage`
+public enum AnyValueProviderStorage {
+  /// The value provider stores a single value that is used on all frames
+  case singleValue(Any)
+
+  /// The value provider stores a group of keyframes
+  ///  - Since we can't interpolate a type-erased `KeyframeGroup`,
+  ///    the interpolation has to be performed in the `interpolate` closure.
+  case keyframes([Keyframe<Any>], interpolate: (AnimationFrameTime) -> Any)
+
+  /// The value provider stores a closure that is invoked on every frame
+  case closure((AnimationFrameTime) -> Any)
+
+  // MARK: Internal
+
+  func value(frame: AnimationFrameTime) -> Any {
+    switch self {
+    case .singleValue(let value):
+      return value
+
+    case .closure(let closure):
+      return closure(frame)
+
+    case .keyframes(_, let valueForFrame):
+      return valueForFrame(frame)
+    }
+  }
+}

package/{lottie-swift/src → Sources}/Public/DynamicProperties/ValueProviders/ColorValueProvider.swift

@@ -5,62 +5,80 @@
 //  Created by Brandon Withrow on 2/4/19.
 //
 
-import Foundation
 import CoreGraphics
+import Foundation
 
 /// A `ValueProvider` that returns a CGColor Value
-public final class ColorValueProvider: AnyValueProvider {
-  
-  /// Returns a Color for a CGColor(Frame Time)
-  public typealias ColorValueBlock = (CGFloat) -> Color
-  
-  /// The color value of the provider.
-  public var color: Color {
-    didSet {
-      hasUpdate = true
-    }
-  }
-  
+public final class ColorValueProvider: ValueProvider {
+
+  // MARK: Lifecycle
+
   /// Initializes with a block provider
   public init(block: @escaping ColorValueBlock) {
     self.block = block
-    self.color = Color(r: 0, g: 0, b: 0, a: 1)
+    color = Color(r: 0, g: 0, b: 0, a: 1)
+    keyframes = nil
   }
-  
+
   /// Initializes with a single color.
   public init(_ color: Color) {
     self.color = color
-    self.block = nil
+    block = nil
+    keyframes = nil
+    hasUpdate = true
+  }
+
+  /// Initializes with multiple colors, with timing information
+  public init(_ keyframes: [Keyframe<Color>]) {
+    self.keyframes = keyframes
+    color = Color(r: 0, g: 0, b: 0, a: 1)
+    block = nil
     hasUpdate = true
   }
-  
+
+  // MARK: Public
+
+  /// Returns a Color for a CGColor(Frame Time)
+  public typealias ColorValueBlock = (CGFloat) -> Color
+
+  /// The color value of the provider.
+  public var color: Color {
+    didSet {
+      hasUpdate = true
+    }
+  }
+
   // MARK: ValueProvider Protocol
-  
+
   public var valueType: Any.Type {
-    return Color.self
+    Color.self
   }
-  
-  public func hasUpdate(frame: CGFloat) -> Bool {
+
+  public var storage: ValueProviderStorage<Color> {
+    if let block = block {
+      return .closure { frame in
+        self.hasUpdate = false
+        return block(frame)
+      }
+    } else if let keyframes = keyframes {
+      return .keyframes(keyframes)
+    } else {
+      hasUpdate = false
+      return .singleValue(color)
+    }
+  }
+
+  public func hasUpdate(frame _: CGFloat) -> Bool {
     if block != nil {
       return true
     }
     return hasUpdate
   }
-  
-  public func value(frame: CGFloat) -> Any {
-    hasUpdate = false
-    let newColor: Color
-    if let block = block {
-      newColor = block(frame)
-    } else {
-      newColor = color
-    }
-    return newColor
-  }
-  
+
   // MARK: Private
-  
-  private var hasUpdate: Bool = true
-  
+
+  private var hasUpdate = true
+
   private var block: ColorValueBlock?
+  private var keyframes: [Keyframe<Color>]?
 }

package/{lottie-swift/src → Sources}/Public/DynamicProperties/ValueProviders/FloatValueProvider.swift

@@ -5,62 +5,66 @@
 //  Created by Brandon Withrow on 2/4/19.
 //
 
-import Foundation
 import CoreGraphics
+import Foundation
 
 /// A `ValueProvider` that returns a CGFloat Value
-public final class FloatValueProvider: AnyValueProvider {
-  
-  /// Returns a CGFloat for a CGFloat(Frame Time)
-  public typealias CGFloatValueBlock = (CGFloat) -> CGFloat
-  
-  public var float: CGFloat {
-    didSet {
-      hasUpdate = true
-    }
-  }
-  
+public final class FloatValueProvider: ValueProvider {
+
+  // MARK: Lifecycle
+
   /// Initializes with a block provider
   public init(block: @escaping CGFloatValueBlock) {
     self.block = block
-    self.float = 0
+    float = 0
   }
-  
+
   /// Initializes with a single float.
   public init(_ float: CGFloat) {
     self.float = float
-    self.block = nil
+    block = nil
     hasUpdate = true
   }
-  
+
+  // MARK: Public
+
+  /// Returns a CGFloat for a CGFloat(Frame Time)
+  public typealias CGFloatValueBlock = (CGFloat) -> CGFloat
+
+  public var float: CGFloat {
+    didSet {
+      hasUpdate = true
+    }
+  }
+
   // MARK: ValueProvider Protocol
-  
+
   public var valueType: Any.Type {
-    return Vector1D.self
+    Vector1D.self
+  }
+
+  public var storage: ValueProviderStorage<Vector1D> {
+    if let block = block {
+      return .closure { frame in
+        self.hasUpdate = false
+        return Vector1D(Double(block(frame)))
+      }
+    } else {
+      hasUpdate = false
+      return .singleValue(Vector1D(Double(float)))
+    }
   }
-  
-  public func hasUpdate(frame: CGFloat) -> Bool {
+
+  public func hasUpdate(frame _: CGFloat) -> Bool {
     if block != nil {
       return true
     }
     return hasUpdate
   }
-  
-  public func value(frame: CGFloat) -> Any {
-    hasUpdate = false
-    let newCGFloat: CGFloat
-    if let block = block {
-      newCGFloat = block(frame)
-    } else {
-      newCGFloat = float
-    }
-    return Vector1D(Double(newCGFloat))
-  }
-  
+
   // MARK: Private
-  
-  private var hasUpdate: Bool = true
-  
+
+  private var hasUpdate = true
+
   private var block: CGFloatValueBlock?
 }
-