lottie-ios 4.2.0 → 4.3.0

package/Sources/Public/{iOS → Controls}/AnimatedSwitch.swift

@@ -6,65 +6,79 @@
 //
 
 import Foundation
-#if os(iOS) || os(tvOS) || os(watchOS) || targetEnvironment(macCatalyst)
+
+#if canImport(UIKit)
 import UIKit
+#elseif canImport(AppKit)
+import AppKit
+#endif
+
+// MARK: - AnimatedSwitch
 
 /// An interactive switch with an 'On' and 'Off' state. When the user taps on the
 /// switch the state is toggled and the appropriate animation is played.
 ///
 /// Both the 'On' and 'Off' have an animation play range associated with their state.
+///
+/// Also available as a SwiftUI view (`LottieSwitch`).
 open class AnimatedSwitch: AnimatedControl {
 
   // MARK: Lifecycle
 
   public override init(
-    animation: LottieAnimation,
+    animation: LottieAnimation?,
     configuration: LottieConfiguration = .shared)
   {
     /// Generate a haptic generator if available.
     #if os(iOS)
-    if #available(iOS 10.0, *) {
-      self.hapticGenerator = HapticGenerator()
-    } else {
-      hapticGenerator = NullHapticGenerator()
-    }
+    hapticGenerator = HapticGenerator()
     #else
     hapticGenerator = NullHapticGenerator()
     #endif
     super.init(animation: animation, configuration: configuration)
+
+    #if canImport(UIKit)
     isAccessibilityElement = true
+    #elseif canImport(AppKit)
+    setAccessibilityElement(true)
+    #endif
+
     updateOnState(isOn: _isOn, animated: false, shouldFireHaptics: false)
   }
 
   public override init() {
     /// Generate a haptic generator if available.
     #if os(iOS)
-    if #available(iOS 10.0, *) {
-      self.hapticGenerator = HapticGenerator()
-    } else {
-      hapticGenerator = NullHapticGenerator()
-    }
+    hapticGenerator = HapticGenerator()
     #else
     hapticGenerator = NullHapticGenerator()
     #endif
+
     super.init()
+
+    #if canImport(UIKit)
     isAccessibilityElement = true
+    #elseif canImport(AppKit)
+    setAccessibilityElement(true)
+    #endif
+
     updateOnState(isOn: _isOn, animated: false, shouldFireHaptics: false)
   }
 
   required public init?(coder aDecoder: NSCoder) {
     /// Generate a haptic generator if available.
     #if os(iOS)
-    if #available(iOS 10.0, *) {
-      self.hapticGenerator = HapticGenerator()
-    } else {
-      hapticGenerator = NullHapticGenerator()
-    }
+    hapticGenerator = HapticGenerator()
     #else
     hapticGenerator = NullHapticGenerator()
     #endif
     super.init(coder: aDecoder)
+
+    #if canImport(UIKit)
     isAccessibilityElement = true
+    #elseif canImport(AppKit)
+    setAccessibilityElement(true)
+    #endif
   }
 
   // MARK: Open
@@ -73,12 +87,23 @@ open class AnimatedSwitch: AnimatedControl {
     updateOnState(isOn: _isOn, animated: animateUpdateWhenChangingAnimation, shouldFireHaptics: false)
   }
 
+  #if canImport(UIKit)
   open override func endTracking(_ touch: UITouch?, with event: UIEvent?) {
     super.endTracking(touch, with: event)
     updateOnState(isOn: !_isOn, animated: true, shouldFireHaptics: true)
     sendActions(for: .valueChanged)
   }
 
+  #elseif canImport(AppKit)
+  open override func handle(_ event: LottieNSControlEvent) {
+    super.handle(event)
+
+    if event == .touchUpInside {
+      updateOnState(isOn: !_isOn, animated: true, shouldFireHaptics: true)
+    }
+  }
+  #endif
+
   // MARK: Public
 
   /// Defines what happens when the user taps the switch while an
@@ -94,10 +119,15 @@ open class AnimatedSwitch: AnimatedControl {
   /// If `false` the switch will not play the animation when changing between animations.
   public var animateUpdateWhenChangingAnimation = true
 
+  #if canImport(UIKit)
   public override var accessibilityTraits: UIAccessibilityTraits {
     set { super.accessibilityTraits = newValue }
     get { super.accessibilityTraits.union(.button) }
   }
+  #endif
+
+  /// A closure that is called when the `isOn` state is updated
+  public var stateUpdated: ((_ isOn: Bool) -> Void)?
 
   /// The current state of the switch.
   public var isOn: Bool {
@@ -136,6 +166,11 @@ open class AnimatedSwitch: AnimatedControl {
 
   // MARK: Internal
 
+  private(set) var onStartProgress: CGFloat = 0
+  private(set) var onEndProgress: CGFloat = 1
+  private(set) var offStartProgress: CGFloat = 1
+  private(set) var offEndProgress: CGFloat = 0
+
   // MARK: Animation State
 
   func updateOnState(isOn: Bool, animated: Bool, shouldFireHaptics: Bool) {
@@ -188,21 +223,27 @@ open class AnimatedSwitch: AnimatedControl {
 
   // MARK: Fileprivate
 
-  fileprivate var onStartProgress: CGFloat = 0
-  fileprivate var onEndProgress: CGFloat = 1
-  fileprivate var offStartProgress: CGFloat = 1
-  fileprivate var offEndProgress: CGFloat = 0
-  fileprivate var _isOn = false
   fileprivate var hapticGenerator: ImpactGenerator
 
+  fileprivate var _isOn = false {
+    didSet {
+      stateUpdated?(_isOn)
+    }
+  }
+
   // MARK: Private
 
   private func updateAccessibilityLabel() {
-    accessibilityValue = _isOn ? NSLocalizedString("On", comment: "On") : NSLocalizedString("Off", comment: "Off")
+    let value = _isOn ? NSLocalizedString("On", comment: "On") : NSLocalizedString("Off", comment: "Off")
+
+    #if canImport(UIKit)
+    accessibilityValue = value
+    #elseif canImport(AppKit)
+    setAccessibilityValue(value)
+    #endif
   }
 
 }
-#endif
 
 // MARK: - ImpactGenerator
 
@@ -210,14 +251,7 @@ protocol ImpactGenerator {
   func generateImpact()
 }
 
-// MARK: - NullHapticGenerator
-
-class NullHapticGenerator: ImpactGenerator {
-  func generateImpact() { }
-}
-
 #if os(iOS)
-@available(iOS 10.0, *)
 class HapticGenerator: ImpactGenerator {
 
   // MARK: Internal
@@ -230,4 +264,10 @@ class HapticGenerator: ImpactGenerator {
 
   fileprivate let impact = UIImpactFeedbackGenerator(style: .light)
 }
+#else
+// MARK: - NullHapticGenerator
+
+class NullHapticGenerator: ImpactGenerator {
+  func generateImpact() { }
+}
 #endif

package/Sources/Public/Controls/LottieButton.swift

@@ -0,0 +1,122 @@
+// Created by Cal Stephens on 8/14/23.
+// Copyright © 2023 Airbnb Inc. All rights reserved.
+
+import SwiftUI
+
+/// A wrapper which exposes Lottie's `AnimatedButton` to SwiftUI
+@available(iOS 13.0, tvOS 13.0, macOS 10.15, *)
+public struct LottieButton: UIViewConfiguringSwiftUIView {
+
+  // MARK: Lifecycle
+
+  public init(animation: LottieAnimation?, action: @escaping () -> Void) {
+    self.animation = animation
+    self.action = action
+  }
+
+  // MARK: Public
+
+  public var body: some View {
+    AnimatedButton.swiftUIView {
+      let button = AnimatedButton(animation: animation, configuration: configuration)
+      button.performAction = action
+      return button
+    }
+    .configure { context in
+      // We check referential equality of the animation before updating as updating the
+      // animation has a side-effect of rebuilding the animation layer, and it would be
+      // prohibitive to do so on every state update.
+      if animation !== context.view.animationView.animation {
+        context.view.animationView.animation = animation
+      }
+
+      #if os(macOS)
+      // Disable the intrinsic content size constraint on the inner animation view,
+      // or the Epoxy `SwiftUIMeasurementContainer` won't size this view correctly.
+      context.view.animationView.isVerticalContentSizeConstraintActive = false
+      context.view.animationView.isHorizontalContentSizeConstraintActive = false
+      #endif
+    }
+    .configurations(configurations)
+  }
+
+  /// Returns a copy of this `LottieView` updated to have the given closure applied to its
+  /// represented `LottieAnimationView` whenever it is updated via the `updateUIView(…)`
+  /// or `updateNSView(…)` method.
+  public func configure(_ configure: @escaping (AnimatedButton) -> Void) -> Self {
+    var copy = self
+    copy.configurations.append { context in
+      configure(context.view)
+    }
+    return copy
+  }
+
+  /// Returns a copy of this view with its `LottieConfiguration` updated to the given value.
+  public func configuration(_ configuration: LottieConfiguration) -> Self {
+    var copy = self
+    copy.configuration = configuration
+
+    copy = copy.configure { view in
+      if view.animationView.configuration != configuration {
+        view.animationView.configuration = configuration
+      }
+    }
+
+    return copy
+  }
+
+  /// Returns a copy of this view configured to animate between the
+  /// given progress values when the given event is triggered
+  public func animate(
+    fromProgress: AnimationProgressTime,
+    toProgress: AnimationProgressTime,
+    on event: LottieControlEvent)
+    -> Self
+  {
+    configure { view in
+      // `setPlayRange` just modifies a dictionary,
+      // so we can just call it on every state update without diffing
+      view.setPlayRange(fromProgress: fromProgress, toProgress: toProgress, event: event)
+    }
+  }
+
+  /// Returns a copy of this view configured to animate between the
+  /// given markers when the given event is triggered
+  public func animate(
+    fromMarker: String,
+    toMarker: String,
+    on event: LottieControlEvent)
+    -> Self
+  {
+    configure { view in
+      // `setPlayRange` just modifies a dictionary,
+      // so we can just call it on every state update without diffing
+      view.setPlayRange(fromMarker: fromMarker, toMarker: toMarker, event: event)
+    }
+  }
+
+  /// Returns a copy of this view using the given value provider for the given keypath.
+  /// The value provider must be `Equatable` to avoid unnecessary state updates / re-renders.
+  public func valueProvider<ValueProvider: AnyValueProvider & Equatable>(
+    _ valueProvider: ValueProvider,
+    for keypath: AnimationKeypath)
+    -> Self
+  {
+    configure { view in
+      if (view.animationView.valueProviders[keypath] as? ValueProvider) != valueProvider {
+        view.animationView.setValueProvider(valueProvider, keypath: keypath)
+      }
+    }
+  }
+
+  // MARK: Internal
+
+  var configurations = [SwiftUIView<AnimatedButton, Void>.Configuration]()
+
+  // MARK: Private
+
+  private let animation: LottieAnimation?
+  private let action: () -> Void
+  private var configuration: LottieConfiguration = .shared
+
+}

package/Sources/Public/Controls/LottieSwitch.swift

@@ -0,0 +1,144 @@
+// Created by Cal Stephens on 8/11/23.
+// Copyright © 2023 Airbnb Inc. All rights reserved.
+
+import SwiftUI
+
+/// A wrapper which exposes Lottie's `AnimatedSwitch` to SwiftUI
+@available(iOS 13.0, tvOS 13.0, macOS 10.15, *)
+public struct LottieSwitch: UIViewConfiguringSwiftUIView {
+
+  // MARK: Lifecycle
+
+  public init(animation: LottieAnimation?) {
+    self.animation = animation
+  }
+
+  // MARK: Public
+
+  public var body: some View {
+    AnimatedSwitch.swiftUIView {
+      let animatedSwitch = AnimatedSwitch(animation: animation, configuration: configuration)
+      animatedSwitch.isOn = isOn?.wrappedValue ?? false
+      return animatedSwitch
+    }
+    .configure { context in
+      // We check referential equality of the animation before updating as updating the
+      // animation has a side-effect of rebuilding the animation layer, and it would be
+      // prohibitive to do so on every state update.
+      if animation !== context.view.animationView.animation {
+        context.view.animationView.animation = animation
+      }
+
+      #if os(macOS)
+      // Disable the intrinsic content size constraint on the inner animation view,
+      // or the Epoxy `SwiftUIMeasurementContainer` won't size this view correctly.
+      context.view.animationView.isVerticalContentSizeConstraintActive = false
+      context.view.animationView.isHorizontalContentSizeConstraintActive = false
+      #endif
+
+      if let isOn = isOn?.wrappedValue, isOn != context.view.isOn {
+        context.view.setIsOn(isOn, animated: true)
+      }
+    }
+    .configurations(configurations)
+  }
+
+  /// Returns a copy of this `LottieView` updated to have the given closure applied to its
+  /// represented `LottieAnimationView` whenever it is updated via the `updateUIView(…)`
+  /// or `updateNSView(…)` method.
+  public func configure(_ configure: @escaping (AnimatedSwitch) -> Void) -> Self {
+    var copy = self
+    copy.configurations.append { context in
+      configure(context.view)
+    }
+    return copy
+  }
+
+  /// Returns a copy of this view with its `LottieConfiguration` updated to the given value.
+  public func configuration(_ configuration: LottieConfiguration) -> Self {
+    var copy = self
+    copy.configuration = configuration
+
+    copy = copy.configure { view in
+      if view.animationView.configuration != configuration {
+        view.animationView.configuration = configuration
+      }
+    }
+
+    return copy
+  }
+
+  /// Returns a copy of this view with the given `Binding` reflecting the `isOn` state of the switch.
+  public func isOn(_ binding: Binding<Bool>) -> Self {
+    var copy = self
+    copy.isOn = binding
+    return copy.configure { view in
+      view.stateUpdated = { isOn in
+        DispatchQueue.main.async {
+          binding.wrappedValue = isOn
+        }
+      }
+    }
+  }
+
+  /// Returns a copy of this view with the "on" animation configured
+  /// to start and end at the given progress values.
+  /// Defaults to playing the entire animation forwards (0...1).
+  public func onAnimation(
+    fromProgress onStartProgress: AnimationProgressTime,
+    toProgress onEndProgress: AnimationProgressTime)
+    -> Self
+  {
+    configure { view in
+      if onStartProgress != view.onStartProgress || onEndProgress != view.onEndProgress {
+        view.setProgressForState(
+          fromProgress: onStartProgress,
+          toProgress: onEndProgress,
+          forOnState: true)
+      }
+    }
+  }
+
+  /// Returns a copy of this view with the "on" animation configured
+  /// to start and end at the given progress values.
+  /// Defaults to playing the entire animation backwards (1...0).
+  public func offAnimation(
+    fromProgress offStartProgress: AnimationProgressTime,
+    toProgress offEndProgress: AnimationProgressTime)
+    -> Self
+  {
+    configure { view in
+      if offStartProgress != view.offStartProgress || offEndProgress != view.offEndProgress {
+        view.setProgressForState(
+          fromProgress: offStartProgress,
+          toProgress: offEndProgress,
+          forOnState: false)
+      }
+    }
+  }
+
+  /// Returns a copy of this view using the given value provider for the given keypath.
+  /// The value provider must be `Equatable` to avoid unnecessary state updates / re-renders.
+  public func valueProvider<ValueProvider: AnyValueProvider & Equatable>(
+    _ valueProvider: ValueProvider,
+    for keypath: AnimationKeypath)
+    -> Self
+  {
+    configure { view in
+      if (view.animationView.valueProviders[keypath] as? ValueProvider) != valueProvider {
+        view.animationView.setValueProvider(valueProvider, keypath: keypath)
+      }
+    }
+  }
+
+  // MARK: Internal
+
+  var configurations = [SwiftUIView<AnimatedSwitch, Void>.Configuration]()
+
+  // MARK: Private
+
+  private let animation: LottieAnimation?
+  private var configuration: LottieConfiguration = .shared
+  private var isOn: Binding<Bool>?
+
+}

package/Sources/Public/Controls/LottieViewType.swift

@@ -0,0 +1,79 @@
+// Created by Cal Stephens on 8/11/23.
+// Copyright © 2023 Airbnb Inc. All rights reserved.
+
+#if canImport(UIKit)
+import UIKit
+
+/// The control base type for this platform.
+///  - `UIControl` on iOS / tvOS and `NSControl` on macOS.
+public typealias LottieControlType = UIControl
+
+/// The `State` type of `LottieControlType`
+///  - `UIControl.State` on iOS / tvOS and `NSControl.StateValue` on macOS.
+public typealias LottieControlState = UIControl.State
+
+/// The event type handled by the `LottieControlType` component for this platform.
+///  - `UIControl.Event` on iOS / tvOS and `LottieNSControlEvent` on macOS.
+public typealias LottieControlEvent = UIControl.Event
+
+extension LottieControlEvent {
+  var id: AnyHashable {
+    rawValue
+  }
+}
+#else
+import AppKit
+
+/// The control base type for this platform.
+///  - `UIControl` on iOS / tvOS and `NSControl` on macOS.
+public typealias LottieControlType = NSControl
+
+/// The `State` type of `LottieControlType`
+///  - `UIControl.State` on iOS / tvOS and `NSControl.StateValue` on macOS.
+public typealias LottieControlState = LottieNSControlState
+
+/// AppKit equivalent of `UIControl.State` for `AnimatedControl`
+public enum LottieNSControlState: UInt, RawRepresentable {
+  /// The normal, or default, state of a control where the control is enabled but neither selected nor highlighted.
+  case normal
+  /// The highlighted state of a control.
+  case highlighted
+}
+
+/// The event type handled by the `LottieControlType` component for this platform.
+///  - `UIControl.Event` on iOS / tvOS and `LottieNSControlEvent` on macOS.
+public typealias LottieControlEvent = LottieNSControlEvent
+
+public struct LottieNSControlEvent: Equatable {
+
+  // MARK: Lifecycle
+
+  public init(_ event: NSEvent.EventType, inside: Bool) {
+    self.event = event
+    self.inside = inside
+  }
+
+  // MARK: Public
+
+  /// macOS equivalent to `UIControl.Event.touchDown`
+  public static let touchDown = LottieNSControlEvent(.leftMouseDown, inside: true)
+
+  /// macOS equivalent to `UIControl.Event.touchUpInside`
+  public static let touchUpInside = LottieNSControlEvent(.leftMouseUp, inside: true)
+
+  /// macOS equivalent to `UIControl.Event.touchUpInside`
+  public static let touchUpOutside = LottieNSControlEvent(.leftMouseUp, inside: false)
+
+  /// The underlying `NSEvent.EventType` of this event, which is roughly equivalent to `UIControl.Event`
+  public var event: NSEvent.EventType
+
+  /// Whether or not the mouse must be inside the control.
+  public var inside: Bool
+
+  // MARK: Internal
+
+  var id: AnyHashable {
+    [AnyHashable(event.rawValue), AnyHashable(inside)]
+  }
+}
+#endif

package/Sources/Public/DotLottie/DotLottieConfiguration.swift

@@ -0,0 +1,24 @@
+//
+// DotLottieConfiguration.swift
+// Lottie
+//
+// Created by Evandro Hoffmann on 19/10/22.
+//
+
+// MARK: - DotLottieConfiguration
+
+/// The `DotLottieConfiguration` model holds the presets extracted from DotLottieAnimation
+/// The presets are used as input to setup `LottieAnimationView` before playing the animation.
+public struct DotLottieConfiguration {
+  /// id of the animation
+  public var id: String
+
+  /// Animation Image Provider
+  public var imageProvider: AnimationImageProvider?
+
+  /// Loop behaviour of animation
+  public var loopMode: LottieLoopMode
+
+  /// Playback speed of animation
+  public var speed: Double
+}

package/Sources/Public/DotLottie/DotLottieFile.swift

@@ -25,19 +25,21 @@ public final class DotLottieFile {
     try decompress(data: data, to: fileUrl)
   }
 
-  // MARK: Internal
+  // MARK: Public
 
   /// Definition for a single animation within a `DotLottieFile`
-  struct Animation {
-    let animation: LottieAnimation
-    let configuration: DotLottieConfiguration
+  public struct Animation {
+    public let animation: LottieAnimation
+    public let configuration: DotLottieConfiguration
   }
 
   /// List of `LottieAnimation` in the file
-  private(set) var animations: [Animation] = []
+  public private(set) var animations: [Animation] = []
+
+  // MARK: Internal
 
   /// Image provider for animations
-  private(set) var imageProvider: AnimationImageProvider?
+  private(set) var imageProvider: DotLottieImageProvider?
 
   /// Animations folder url
   lazy var animationsUrl: URL = fileUrl.appendingPathComponent("\(DotLottieFile.animationsFolderName)")
@@ -60,6 +62,12 @@ public final class DotLottieFile {
     }
   }
 
+  /// The `LottieAnimation` and `DotLottieConfiguration` for the given animation index in this file
+  func animation(at index: Int) -> DotLottieFile.Animation? {
+    guard index < animations.count else { return nil }
+    return animations[index]
+  }
+
   // MARK: Private
 
   private static let manifestFileName = "manifest.json"
@@ -136,3 +144,10 @@ extension String {
     (self as NSString).deletingPathExtension
   }
 }
+
+// MARK: - DotLottieFile + Sendable
+
+// Mark `DotLottieFile` as `@unchecked Sendable` to allow it to be used when strict concurrency is enabled.
+// In the future, it may be necessary to make changes to the internal implementation of `DotLottieFile`
+// to make it truly thread-safe.
+extension DotLottieFile: @unchecked Sendable { }