lottie-ios 4.2.0 → 4.3.0

package/Sources/Public/Configuration/LottieConfiguration.swift

@@ -0,0 +1,47 @@
+// Created by Cal Stephens on 12/13/21.
+// Copyright © 2021 Airbnb Inc. All rights reserved.
+
+import QuartzCore
+
+/// Global configuration options for Lottie animations
+public struct LottieConfiguration: Hashable {
+
+  // MARK: Lifecycle
+
+  public init(
+    renderingEngine: RenderingEngineOption = .automatic,
+    decodingStrategy: DecodingStrategy = .dictionaryBased,
+    colorSpace: CGColorSpace = CGColorSpaceCreateDeviceRGB(),
+    reducedMotionOption: ReducedMotionOption = .systemReducedMotionToggle)
+  {
+    self.renderingEngine = renderingEngine
+    self.decodingStrategy = decodingStrategy
+    self.colorSpace = colorSpace
+    self.reducedMotionOption = reducedMotionOption
+  }
+
+  // MARK: Public
+
+  /// The global configuration of Lottie,
+  /// which applies to all `LottieAnimationView`s by default.
+  public static var shared = LottieConfiguration()
+
+  /// The rendering engine implementation to use when displaying an animation
+  ///  - Defaults to `RenderingEngineOption.automatic`, which uses the
+  ///    Core Animation rendering engine for supported animations, and
+  ///    falls back to using the Main Thread rendering engine for
+  ///    animations that use features not supported by the Core Animation engine.
+  public var renderingEngine: RenderingEngineOption
+
+  /// The decoding implementation to use when parsing an animation JSON file
+  public var decodingStrategy: DecodingStrategy
+
+  /// Options for controlling animation behavior in response to user / system "reduced motion" configuration.
+  ///  - Defaults to `ReducedMotionOption.systemReducedMotionToggle`, which returns `.reducedMotion`
+  ///    when the system `UIAccessibility.isReduceMotionEnabled` option is `true`.
+  public var reducedMotionOption: ReducedMotionOption
+
+  /// The color space to be used for rendering
+  ///  - Defaults to `CGColorSpaceCreateDeviceRGB()`
+  public var colorSpace: CGColorSpace
+}

package/Sources/Public/Configuration/ReducedMotionOption.swift

@@ -0,0 +1,114 @@
+// Created by Cal Stephens on 7/14/23.
+// Copyright © 2023 Airbnb Inc. All rights reserved.
+
+#if canImport(UIKit)
+import UIKit
+#elseif canImport(AppKit)
+import AppKit
+#endif
+
+// MARK: - ReducedMotionOption
+
+/// Options for controlling animation behavior in response to user / system "reduced motion" configuration
+public enum ReducedMotionOption {
+  /// Always use the specific given `ReducedMotionMode` value.
+  case specific(ReducedMotionMode)
+
+  /// Dynamically check the given `ReducedMotionOptionProvider` each time an animation begins.
+  ///  - Includes a Hashable `dataID` to support `ReducedMotionOption`'s `Hashable` requirement,
+  ///    which is required due to `LottieConfiguration`'s existing `Hashable` requirement.
+  case dynamic(ReducedMotionOptionProvider, dataID: AnyHashable)
+}
+
+extension ReducedMotionOption {
+  /// The standard behavior where Lottie animations play normally with no overrides.
+  /// By default this mode is used when the system "reduced motion" option is disabled.
+  public static var standardMotion: ReducedMotionOption { .specific(.standardMotion) }
+
+  /// Lottie animations with a "reduced motion" marker will play that marker instead of any other animations.
+  /// By default this mode is used when the system "reduced motion" option is enabled.
+  ///  - Valid marker names include "reduced motion", "reducedMotion", "reduced_motion" (case insensitive).
+  public static var reducedMotion: ReducedMotionOption { .specific(.reducedMotion) }
+
+  /// A `ReducedMotionOptionProvider` that returns `.reducedMotion` when
+  /// the system `UIAccessibility.isReduceMotionEnabled` option is `true`.
+  /// This is the default option of `LottieConfiguration`.
+  public static var systemReducedMotionToggle: ReducedMotionOption {
+    .dynamic(SystemReducedMotionOptionProvider(), dataID: ObjectIdentifier(SystemReducedMotionOptionProvider.self))
+  }
+}
+
+extension ReducedMotionOption {
+  /// The current `ReducedMotionMode` based on the currently selected option.
+  public var currentReducedMotionMode: ReducedMotionMode {
+    switch self {
+    case .specific(let specificMode):
+      return specificMode
+    case .dynamic(let optionProvider, _):
+      return optionProvider.currentReducedMotionMode
+    }
+  }
+}
+
+// MARK: Hashable
+
+extension ReducedMotionOption: Hashable {
+  public static func ==(_ lhs: ReducedMotionOption, _ rhs: ReducedMotionOption) -> Bool {
+    switch (lhs, rhs) {
+    case (.specific(let lhsMode), .specific(let rhsMode)):
+      return lhsMode == rhsMode
+    case (.dynamic(_, let lhsDataID), .dynamic(_, dataID: let rhsDataID)):
+      return lhsDataID == rhsDataID
+    case (.dynamic, .specific), (.specific, .dynamic):
+      return false
+    }
+  }
+
+  public func hash(into hasher: inout Hasher) {
+    switch self {
+    case .specific(let mode):
+      hasher.combine(mode)
+    case .dynamic(_, let dataID):
+      hasher.combine(dataID)
+    }
+  }
+}
+
+// MARK: - ReducedMotionMode
+
+public enum ReducedMotionMode: Hashable {
+  /// The default behavior where Lottie animations play normally with no overrides
+  /// By default this mode is used when the system "reduced motion" option is disabled.
+  case standardMotion
+
+  /// Lottie animations with a "reduced motion" marker will play that marker instead of any other animations.
+  /// By default this mode is used when the system "reduced motion" option is enabled.
+  case reducedMotion
+}
+
+// MARK: - ReducedMotionOptionProvider
+
+/// A type that returns a dynamic `ReducedMotionMode` which is checked when playing a Lottie animation.
+public protocol ReducedMotionOptionProvider {
+  var currentReducedMotionMode: ReducedMotionMode { get }
+}
+
+// MARK: - SystemReducedMotionOptionProvider
+
+/// A `ReducedMotionOptionProvider` that returns `.reducedMotion` when
+/// the system `UIAccessibility.isReduceMotionEnabled` option is `true`.
+public struct SystemReducedMotionOptionProvider: ReducedMotionOptionProvider {
+  public init() { }
+
+  public var currentReducedMotionMode: ReducedMotionMode {
+    #if canImport(UIKit)
+    if UIAccessibility.isReduceMotionEnabled {
+      return .reducedMotion
+    } else {
+      return .standardMotion
+    }
+    #else
+    return .standardMotion
+    #endif
+  }
+}

package/Sources/Public/{LottieConfiguration.swift → Configuration/RenderingEngineOption.swift}

@@ -1,45 +1,5 @@
-// Created by Cal Stephens on 12/13/21.
-// Copyright © 2021 Airbnb Inc. All rights reserved.
-
-import QuartzCore
-
-// MARK: - LottieConfiguration
-
-/// Global configuration options for Lottie animations
-public struct LottieConfiguration: Hashable {
-
-  // MARK: Lifecycle
-
-  public init(
-    renderingEngine: RenderingEngineOption = .automatic,
-    decodingStrategy: DecodingStrategy = .dictionaryBased,
-    colorSpace: CGColorSpace = CGColorSpaceCreateDeviceRGB())
-  {
-    self.renderingEngine = renderingEngine
-    self.decodingStrategy = decodingStrategy
-    self.colorSpace = colorSpace
-  }
-
-  // MARK: Public
-
-  /// The global configuration of Lottie,
-  /// which applies to all `LottieAnimationView`s by default.
-  public static var shared = LottieConfiguration()
-
-  /// The rendering engine implementation to use when displaying an animation
-  ///  - Defaults to `RenderingEngineOption.automatic`, which uses the
-  ///    Core Animation rendering engine for supported animations, and
-  ///    falls back to using the Main Thread rendering engine for
-  ///    animations that use features not supported by the Core Animation engine.
-  public var renderingEngine: RenderingEngineOption
-
-  /// The decoding implementation to use when parsing an animation JSON file
-  public var decodingStrategy: DecodingStrategy
-
-  /// The color space to be used for rendering
-  ///  - Defaults to `CGColorSpaceCreateDeviceRGB()`
-  public var colorSpace: CGColorSpace
-}
+// Created by Cal Stephens on 7/14/23.
+// Copyright © 2023 Airbnb Inc. All rights reserved.
 
 // MARK: - RenderingEngineOption
 
@@ -151,18 +111,3 @@ extension RenderingEngine: RawRepresentable, CustomStringConvertible {
     rawValue
   }
 }
-
-// MARK: - DecodingStrategy
-
-/// How animation files should be decoded
-public enum DecodingStrategy: Hashable {
-  /// Use Codable. This is was the default strategy introduced on Lottie 3, but should be rarely
-  /// used as it's slower than `dictionaryBased`. Kept here for any possible compatibility issues
-  /// that may come up, but consider it soft-deprecated.
-  case legacyCodable
-
-  /// Manually deserialize a dictionary into an Animation.
-  /// This should be at least 2-3x faster than using Codable and due to that
-  /// it's the default as of Lottie 4.x.
-  case dictionaryBased
-}

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

@@ -6,38 +6,61 @@
 //
 
 import Foundation
-#if os(iOS) || os(tvOS) || os(watchOS) || targetEnvironment(macCatalyst)
+
+#if canImport(UIKit)
 import UIKit
+#elseif canImport(AppKit)
+import AppKit
+#endif
+
+// MARK: - AnimatedButton
+
 /// An interactive button that plays an animation when pressed.
 open class AnimatedButton: AnimatedControl {
 
   // MARK: Lifecycle
 
   public override init(
-    animation: LottieAnimation,
+    animation: LottieAnimation?,
     configuration: LottieConfiguration = .shared)
   {
     super.init(animation: animation, configuration: configuration)
+
+    #if canImport(UIKit)
     isAccessibilityElement = true
+    #elseif canImport(AppKit)
+    setAccessibilityElement(true)
+    #endif
   }
 
   public override init() {
     super.init()
+
+    #if canImport(UIKit)
     isAccessibilityElement = true
+    #elseif canImport(AppKit)
+    setAccessibilityElement(true)
+    #endif
   }
 
   required public init?(coder aDecoder: NSCoder) {
     super.init(coder: aDecoder)
+
+    #if canImport(UIKit)
     isAccessibilityElement = true
+    #elseif canImport(AppKit)
+    setAccessibilityElement(true)
+    #endif
   }
 
   // MARK: Open
 
+  #if canImport(UIKit)
   open override func beginTracking(_ touch: UITouch, with event: UIEvent?) -> Bool {
     let _ = super.beginTracking(touch, with: event)
     let touchEvent = UIControl.Event.touchDown
-    if let playrange = rangesForEvents[touchEvent.rawValue] {
-      animationView.play(fromProgress: playrange.from, toProgress: playrange.to, loopMode: LottieLoopMode.playOnce)
+    if let playRange = rangesForEvents[touchEvent.id] {
+      animationView.play(fromProgress: playRange.from, toProgress: playRange.to, loopMode: .playOnce)
     }
     return true
   }
@@ -47,40 +70,60 @@ open class AnimatedButton: AnimatedControl {
     let touchEvent: UIControl.Event
     if let touch = touch, bounds.contains(touch.location(in: self)) {
       touchEvent = UIControl.Event.touchUpInside
+      performAction?()
     } else {
       touchEvent = UIControl.Event.touchUpOutside
     }
 
-    if let playrange = rangesForEvents[touchEvent.rawValue] {
-      animationView.play(fromProgress: playrange.from, toProgress: playrange.to, loopMode: LottieLoopMode.playOnce)
+    if let playRange = rangesForEvents[touchEvent.id] {
+      animationView.play(fromProgress: playRange.from, toProgress: playRange.to, loopMode: .playOnce)
     }
   }
 
+  #elseif canImport(AppKit)
+  open override func handle(_ event: LottieNSControlEvent) {
+    super.handle(event)
+
+    if let playRange = rangesForEvents[event.id] {
+      animationView.play(fromProgress: playRange.from, toProgress: playRange.to, loopMode: .playOnce)
+    }
+
+    if event == .touchUpInside {
+      performAction?()
+    }
+  }
+  #endif
+
   // MARK: Public
 
+  /// A closure that is called when the button is pressed / clicked
+  public var performAction: (() -> Void)?
+
+  #if canImport(UIKit)
   public override var accessibilityTraits: UIAccessibilityTraits {
     set { super.accessibilityTraits = newValue }
     get { super.accessibilityTraits.union(.button) }
   }
+  #endif
 
   /// Sets the play range for the given UIControlEvent.
-  public func setPlayRange(fromProgress: AnimationProgressTime, toProgress: AnimationProgressTime, event: UIControl.Event) {
-    rangesForEvents[event.rawValue] = (from: fromProgress, to: toProgress)
+  public func setPlayRange(fromProgress: AnimationProgressTime, toProgress: AnimationProgressTime, event: LottieControlEvent) {
+    rangesForEvents[event.id] = (from: fromProgress, to: toProgress)
   }
 
   /// Sets the play range for the given UIControlEvent.
-  public func setPlayRange(fromMarker fromName: String, toMarker toName: String, event: UIControl.Event) {
+  public func setPlayRange(fromMarker fromName: String, toMarker toName: String, event: LottieControlEvent) {
     if
       let start = animationView.progressTime(forMarker: fromName),
       let end = animationView.progressTime(forMarker: toName)
     {
-      rangesForEvents[event.rawValue] = (from: start, to: end)
+      rangesForEvents[event.id] = (from: start, to: end)
     }
   }
 
   // MARK: Private
 
-  private var rangesForEvents: [UInt : (from: CGFloat, to: CGFloat)] =
-    [UIControl.Event.touchUpInside.rawValue : (from: 0, to: 1)]
+  private var rangesForEvents: [AnyHashable : (from: CGFloat, to: CGFloat)] = {
+    [LottieControlEvent.touchUpInside.id: (from: 0, to: 1)]
+  }()
 }
-#endif

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

@@ -5,9 +5,15 @@
 //  Created by Brandon Withrow on 2/4/19.
 //
 
-import Foundation
-#if os(iOS) || os(tvOS) || os(watchOS) || targetEnvironment(macCatalyst)
+#if canImport(UIKit)
 import UIKit
+#elseif canImport(AppKit)
+import AppKit
+#endif
+
+import Foundation
+
+// MARK: - AnimatedControl
 
 /// Lottie comes prepacked with a two Animated Controls, `AnimatedSwitch` and
 /// `AnimatedButton`. Both of these controls are built on top of `AnimatedControl`
@@ -24,21 +30,21 @@ import UIKit
 /// of its layers.
 ///
 /// NOTE: Do not initialize directly. This is intended to be subclassed.
-open class AnimatedControl: UIControl {
+open class AnimatedControl: LottieControlType {
 
   // MARK: Lifecycle
 
   // MARK: Initializers
 
   public init(
-    animation: LottieAnimation,
+    animation: LottieAnimation?,
     configuration: LottieConfiguration = .shared)
   {
     animationView = LottieAnimationView(
       animation: animation,
       configuration: configuration)
 
-    super.init(frame: animation.bounds)
+    super.init(frame: animation?.bounds ?? .zero)
     commonInit()
   }
 
@@ -64,11 +70,13 @@ open class AnimatedControl: UIControl {
     }
   }
 
+  #if canImport(UIKit)
   open override var isSelected: Bool {
     didSet {
       updateForState()
     }
   }
+  #endif
 
   open override var isHighlighted: Bool {
     didSet {
@@ -80,6 +88,7 @@ open class AnimatedControl: UIControl {
     animationView.intrinsicContentSize
   }
 
+  #if canImport(UIKit)
   open override func beginTracking(_ touch: UITouch, with event: UIEvent?) -> Bool {
     updateForState()
     return super.beginTracking(touch, with: event)
@@ -100,6 +109,50 @@ open class AnimatedControl: UIControl {
     super.cancelTracking(with: event)
   }
 
+  #elseif canImport(AppKit)
+  open override func mouseDown(with mouseDownEvent: NSEvent) {
+    guard let window = window else { return }
+
+    currentState = .highlighted
+    updateForState()
+    handle(LottieControlEvent(mouseDownEvent.type, inside: eventIsInside(mouseDownEvent)))
+
+    // AppKit mouse-tracking loop from:
+    // https://developer.apple.com/library/archive/documentation/Cocoa/Conceptual/EventOverview/HandlingMouseEvents/HandlingMouseEvents.html#//apple_ref/doc/uid/10000060i-CH6-SW4
+    var keepOn = true
+    while
+      keepOn,
+      let event = window.nextEvent(
+        matching: .any,
+        until: .distantFuture,
+        inMode: .eventTracking,
+        dequeue: true)
+    {
+      if event.type == .leftMouseUp {
+        keepOn = false
+      }
+
+      let isInside = eventIsInside(event)
+      handle(LottieControlEvent(event.type, inside: isInside))
+
+      let expectedState = (isInside && keepOn) ? LottieNSControlState.highlighted : .normal
+      if currentState != expectedState {
+        currentState = expectedState
+        updateForState()
+      }
+    }
+  }
+
+  func handle(_: LottieNSControlEvent) {
+    // To be overridden in subclasses
+  }
+
+  private func eventIsInside(_ event: NSEvent) -> Bool {
+    let mouseLocation = convert(event.locationInWindow, from: nil)
+    return isMousePoint(mouseLocation, in: bounds)
+  }
+  #endif
+
   open func animationDidSet() { }
 
   // MARK: Public
@@ -112,7 +165,11 @@ open class AnimatedControl: UIControl {
     didSet {
       animationView.animation = animation
       animationView.bounds = animation?.bounds ?? .zero
+      #if canImport(UIKit)
       setNeedsLayout()
+      #elseif canImport(AppKit)
+      needsLayout = true
+      #endif
       updateForState()
       animationDidSet()
     }
@@ -125,7 +182,7 @@ open class AnimatedControl: UIControl {
   }
 
   /// Sets which Animation Layer should be visible for the given state.
-  public func setLayer(named: String, forState: UIControl.State) {
+  public func setLayer(named: String, forState: LottieControlState) {
     stateMap[forState.rawValue] = named
     updateForState()
   }
@@ -139,10 +196,19 @@ open class AnimatedControl: UIControl {
 
   var stateMap: [UInt: String] = [:]
 
+  #if canImport(UIKit)
+  var currentState: LottieControlState {
+    state
+  }
+
+  #elseif canImport(AppKit)
+  var currentState = LottieControlState.normal
+  #endif
+
   func updateForState() {
     guard let animationLayer = animationView.animationLayer else { return }
     if
-      let layerName = stateMap[state.rawValue],
+      let layerName = stateMap[currentState.rawValue],
       let stateLayer = animationLayer.layer(for: AnimationKeypath(keypath: layerName))
     {
       for layer in animationLayer._animationLayers {
@@ -159,17 +225,23 @@ open class AnimatedControl: UIControl {
   // MARK: Private
 
   private func commonInit() {
+    #if canImport(UIKit)
     animationView.clipsToBounds = false
     clipsToBounds = true
+    #endif
+
     animationView.translatesAutoresizingMaskIntoConstraints = false
     animationView.backgroundBehavior = .forceFinish
     addSubview(animationView)
     animationView.contentMode = .scaleAspectFit
+
+    #if canImport(UIKit)
     animationView.isUserInteractionEnabled = false
+    #endif
+
     animationView.leadingAnchor.constraint(equalTo: leadingAnchor).isActive = true
     animationView.trailingAnchor.constraint(equalTo: trailingAnchor).isActive = true
     animationView.topAnchor.constraint(equalTo: topAnchor).isActive = true
     animationView.bottomAnchor.constraint(equalTo: bottomAnchor).isActive = true
   }
 }
-#endif