DotLottie Support

/**
 * Main class for loading and managing .lottie files
 * Loads compressed animation packages with embedded assets
 */
public final class DotLottieFile {
    
    /**
     * Definition for a single animation within a DotLottieFile
     * Contains both the animation data and its configuration
     */
    public struct Animation {
        /** The LottieAnimation data */
        public let animation: LottieAnimation
        /** Configuration settings for this animation */
        public let configuration: DotLottieConfiguration
    }
    
    /** List of animations contained in this .lottie file */
    public private(set) var animations: [Animation]
    
    /**
     * Load DotLottie file from bundle by name
     * @param name - Name of .lottie file in bundle (without extension)
     * @param bundle - Bundle containing the file (defaults to main bundle)
     * @param subdirectory - Subdirectory within bundle (optional)
     * @returns DotLottieFile instance, nil if file not found
     */
    public static func named(
        _ name: String,
        bundle: Bundle = Bundle.main,
        subdirectory: String? = nil
    ) -> DotLottieFile?
    
    /**
     * Load DotLottie file from file path
     * @param filepath - Full path to .lottie file
     * @returns DotLottieFile instance, nil if file not found
     */
    public static func filepath(_ filepath: String) -> DotLottieFile?
    
    /**
     * Load DotLottie file from URL
     * @param url - URL to .lottie file (local or remote)
     * @returns DotLottieFile instance, nil if loading fails
     */
    public static func from(url: URL) -> DotLottieFile?
    
    /**
     * Load DotLottie file from Data
     * @param data - Raw .lottie file data
     * @param filename - Original filename for temp file creation
     * @returns DotLottieFile instance, nil if parsing fails
     */
    public init(data: Data, filename: String) throws
    
    /**
     * Get animation by ID
     * @param id - Animation ID string (optional, returns first if nil)
     * @returns Animation wrapper with LottieAnimation and configuration
     */
    public func animation(for id: String? = nil) -> Animation?
    
    /**
     * Get animation by index
     * @param index - Zero-based index of animation
     * @returns Animation wrapper at index, nil if out of bounds
     */
    public func animation(at index: Int) -> Animation?
}

import Lottie

// Load from bundle
if let dotLottie = DotLottieFile.named("my-animations") {
    // Get first animation
    if let animation = dotLottie.animation() {
        let animationView = LottieAnimationView()
        animationView.animation = animation.animation
        animationView.loopMode = animation.configuration.loopMode
        animationView.animationSpeed = CGFloat(animation.configuration.speed)
    }
    
    // Get specific animation by ID
    if let specificAnimation = dotLottie.animation(for: "button-hover") {
        // Use the animation
    }
}

// Load from file path
if let dotLottie = DotLottieFile.filepath("/path/to/animations.lottie") {
    // Use animations
}

/**
 * Configuration settings for DotLottie animations
 * Contains presets extracted from .lottie manifest
 */
public struct DotLottieConfiguration {
    
    /** Unique identifier for the animation */
    public var id: String
    
    /** Loop behavior for this animation */
    public var loopMode: LottieLoopMode
    
    /** Playback speed multiplier */
    public var speed: Double
    
    /** Image provider for embedded images (read-only) */
    public var imageProvider: AnimationImageProvider? { get }
}

/**
 * Configuration components that can be applied to LottieAnimationView
 * Controls which DotLottie settings override manual settings
 */
public struct DotLottieConfigurationComponents: OptionSet {
    
    /** Apply image provider from DotLottie configuration */
    public static let imageProvider: DotLottieConfigurationComponents
    
    /** Apply loop mode from DotLottie configuration */
    public static let loopMode: DotLottieConfigurationComponents
    
    /** Apply animation speed from DotLottie configuration */
    public static let animationSpeed: DotLottieConfigurationComponents
    
    /** Apply all configuration components */
    public static let all: DotLottieConfigurationComponents
    
    /** Apply no configuration components */
    public static let none: DotLottieConfigurationComponents
    
    public let rawValue: Int
    public init(rawValue: Int)
}

/**
 * Protocol for caching DotLottie files
 * Enables performance optimization for repeated loads
 */
public protocol DotLottieCacheProvider {
    
    /**
     * Retrieve cached DotLottie file
     * @param key - Cache key string
     * @returns Cached DotLottieFile, nil if not cached
     */
    func file(forKey key: String) -> DotLottieFile?
    
    /**
     * Store DotLottie file in cache
     * @param file - DotLottieFile to cache
     * @param key - Cache key string
     */
    func setFile(_ file: DotLottieFile, forKey key: String)
    
    /**
     * Remove all cached files
     */
    func clearCache()
}

/**
 * Default implementation of DotLottie caching
 * Thread-safe LRU cache with configurable limits
 */
public class DotLottieCache: DotLottieCacheProvider {
    
    /** Shared cache instance */
    public static let shared: DotLottieCache
    
    /** Maximum number of cached files */
    public var countLimit: Int { get set }
    
    /** Maximum total size of cached files in bytes */
    public var totalCostLimit: Int { get set }
    
    public func file(forKey key: String) -> DotLottieFile?
    public func setFile(_ file: DotLottieFile, forKey key: String)
    public func clearCache()
}

// Configure DotLottie cache
DotLottieCache.shared.countLimit = 20
DotLottieCache.shared.totalCostLimit = 50 * 1024 * 1024 // 50MB

// Load with automatic caching
if let dotLottie = DotLottieFile.named("animations") {
    // Subsequent loads will use cached version
    let cachedDotLottie = DotLottieFile.named("animations") // From cache
}

// Manual cache management
let cache = DotLottieCache.shared
if let cachedFile = cache.file(forKey: "my-key") {
    // Use cached file
} else {
    // Load and cache manually
    if let newFile = DotLottieFile.named("animations") {
        cache.setFile(newFile, forKey: "my-key")
    }
}

// LottieView extensions for DotLottie support
extension LottieView {
    
    /**
     * Initialize with DotLottie file and animation ID
     * @param dotLottie - DotLottie file containing animations
     * @param animationId - Specific animation ID to display
     * @param configuration - Which configuration components to apply
     */
    public init(
        dotLottie: DotLottieFile?,
        animationId: String = "",
        configuration: DotLottieConfigurationComponents = .all
    )
}

// LottieAnimationView extensions for DotLottie support  
extension LottieAnimationView {
    
    /**
     * Initialize with DotLottie file
     * @param dotLottie - DotLottie file containing animations
     * @param animationId - Specific animation ID to display (empty for first)
     * @param configuration - Which configuration components to apply
     */
    public convenience init(
        dotLottie: DotLottieFile?,
        animationId: String = "",
        configuration: DotLottieConfigurationComponents = .all
    )
}

// SwiftUI usage
struct ContentView: View {
    var body: some View {
        if let dotLottie = DotLottieFile.named("ui-animations") {
            LottieView(dotLottie: dotLottie, animationId: "loading")
                .frame(width: 200, height: 200)
                
            // With custom configuration
            LottieView(
                dotLottie: dotLottie, 
                animationId: "button-press",
                configuration: [.loopMode, .animationSpeed]
            )
        }
    }
}

// UIKit usage
let animationView = LottieAnimationView(
    dotLottie: dotLottieFile,
    animationId: "success",
    configuration: .all
)
view.addSubview(animationView)