Support animation and debounce with native bindings (#1007)

* Support animation with native bindings

* Fix issue with sending native bindings to incorrect LiveView

* Fix test suite

* Fix redirect disconnection

* Support debouncing native bindings with `binding-attribute:debounce`

* Support global and scoped persistence modes

* Attempt to fix assertMatch

---------

Co-authored-by: May Matyi <[email protected]>

Author: carson-katri

Sources/LiveViewNative/Coordinators/LiveSessionCoordinator.swift

@@ -41,7 +41,7 @@ public class LiveSessionCoordinator<R: RootRegistry>: ObservableObject {
     public private(set) var url: URL
 
     @Published var navigationPath = [LiveNavigationEntry<R>]()
-    private(set) var rootCoordinator: LiveViewCoordinator<R>!
+    var rootCoordinator: LiveViewCoordinator<R>!
 
     internal let config: LiveSessionConfiguration
 
@@ -321,6 +321,7 @@ public class LiveSessionCoordinator<R: RootRegistry>: ObservableObject {
         case .replaceTop:
             let coordinator = (navigationPath.last?.coordinator ?? rootCoordinator)!
             coordinator.url = redirect.to
+            coordinator.disconnect()
             let entry = LiveNavigationEntry(url: redirect.to, coordinator: coordinator)
             switch redirect.kind {
             case .push:

Sources/LiveViewNative/Coordinators/LiveViewCoordinator.swift

@@ -253,6 +253,7 @@ public class LiveViewCoordinator<R: RootRegistry>: ObservableObject {
         connectParams["_csrf_token"] = session.phxCSRFToken
         connectParams["_platform"] = "swiftui"
         connectParams["_platform_meta"] = try getPlatformMetadata()
+        connectParams["_global_native_bindings"] = Dictionary(uniqueKeysWithValues: R.globalBindings.map({ ($0, R.bindingValue(forKey: $0, in: nil)) }))
 
         let params: Payload = [
             "session": session.phxSession,

Sources/LiveViewNative/NavStackEntryView.swift

@@ -11,15 +11,14 @@ import LiveViewNativeCore
 struct NavStackEntryView<R: RootRegistry>: View {
     private let entry: LiveNavigationEntry<R>
     @ObservedObject private var coordinator: LiveViewCoordinator<R>
-    @StateObject private var liveViewModel = LiveViewModel()
+    @StateObject private var liveViewModel = LiveViewModel(bindingValue: R.bindingValue, setBindingValue: R.setBindingValue, globalBindings: { R.globalBindings }, registerGlobalBinding: R.registerGlobalBinding)
 
     init(_ entry: LiveNavigationEntry<R>) {
         self.entry = entry
         self.coordinator = entry.coordinator
     }
 
     var body: some View {
-        let _ = Self._printChanges()
         elementTree
             .environmentObject(liveViewModel)
             .onReceive(coordinator.$document) { newDocument in
@@ -29,11 +28,15 @@ struct NavStackEntryView<R: RootRegistry>: View {
                 }
             }
             .onReceive(coordinator.receiveEvent("_native_bindings"), perform: liveViewModel.updateBindings)
+            .onReceive(coordinator.receiveEvent("_native_bindings_init"), perform: liveViewModel.initBindings(payload:))
             .onReceive(
                 liveViewModel.bindingUpdatedByClient
-                    .collect(.byTime(RunLoop.main, RunLoop.main.minimumTolerance))
+                    .collect(.byTime(RunLoop.current, RunLoop.current.minimumTolerance))
             ) { updates in
                 Task {
+                    // In some cases, the bindings will update as the page is navigating.
+                    // Don't send the bindings to the wrong live view in this case.
+                    guard entry.url == coordinator.url else { return }
                     try? await coordinator.pushEvent(type: "_native_bindings", event: "_native_bindings", value: Dictionary(updates, uniquingKeysWith: { cur, new in new }))
                 }
             }

Sources/LiveViewNative/Property Wrappers/LiveBinding.swift

@@ -149,40 +149,17 @@ public struct LiveBinding<Value: Codable> {
     /// Setting this property will send an event to the server to update its value as well.
     public var wrappedValue: Value {
         get {
-            let valueError: Error?
-            if let bindingName {
-                do {
-                    return try data.getValue(from: liveViewModel, bindingName: bindingName)
-                } catch {
-                    valueError = error
-                }
-            } else {
-                valueError = nil
-            }
-            if case .local(let value) = data.mode {
-                return value
+            if let boundValue = data.value {
+                return boundValue
             } else if let initialLocalValue {
                 return initialLocalValue
             } else {
-                if let valueError {
-                    fatalError(valueError.localizedDescription)
-                } else {
-                    fatalError("@LiveBinding must have binding name or default value")
-                }
+                fatalError("@LiveBinding must have binding name or default value")
             }
         }
         nonmutating set {
-            // update the local value
-            data.mode = .local(newValue)
-            data.objectWillChange.send()
-            // if we are bound, update the view model, which will send an update to the backend
-            if let bindingName {
-                let encoder = FragmentEncoder()
-                // todo: if encoding fails, what should happen?
-                try! newValue.encode(to: encoder)
-                data.skipNextUpdate = true
-                liveViewModel.setBinding(bindingName, to: encoder.unwrap() as Any)
-            }
+            data.value = newValue
+            data.localValueChanged.send() // make sure to send a signal when the client changes the value.
         }
     }
 
@@ -200,7 +177,20 @@ public struct LiveBinding<Value: Codable> {
 
 extension LiveBinding: DynamicProperty {
     public func update() {
-        // don't need to do anything, just need to conform to DynamicProperty to make sure our @StateObject gets installed
+        switch bindingNameSource {
+        case let .attribute(attribute):
+            data.bind(
+                to: liveViewModel,
+                bindingName: bindingName,
+                debounce: (try? element.attributeValue(Double.self, for: .init(namespace: attribute.name, name: "debounce"))) ?? 0
+            )
+        default:
+            data.bind(
+                to: liveViewModel,
+                bindingName: bindingName,
+                debounce: 0
+            )
+        }
     }
 }
 
@@ -214,52 +204,46 @@ extension LiveBinding {
 
 extension LiveBinding {
     class Data: ObservableObject {
-        var mode: Mode = .uninitialized
-        var skipNextUpdate = false
-        private var serverCancellable: AnyCancellable?
-        private var clientCancellable: AnyCancellable?
+        /// The current value of the binding.
+        var value: Value?
 
-        func getValue(from liveViewModel: LiveViewModel, bindingName: String) throws -> Value {
-            switch mode {
-            case .uninitialized:
-                serverCancellable = liveViewModel.bindingUpdatedByServer
-                    .filter { $0.0 == bindingName }
-                    .sink { [unowned self] _ in
-                        self.mode = .needsUpdateFromViewModel
-                        self.objectWillChange.send()
-                    }
-                clientCancellable = liveViewModel.bindingUpdatedByClient
-                    .filter { $0.0 == bindingName }
-                    .sink { [unowned self] _ in
-                        if self.skipNextUpdate {
-                            self.skipNextUpdate = false
-                        } else {
-                            self.mode = .needsUpdateFromViewModel
-                            self.objectWillChange.send()
-                        }
-                    }
-                return try getValueFromViewModel(liveViewModel, bindingName: bindingName)
-            case .needsUpdateFromViewModel:
-                return try getValueFromViewModel(liveViewModel, bindingName: bindingName)
-            case .local(let value):
-                return value
-            }
-        }
+        /// A publisher used to track when the value is changed by the client.
+        let localValueChanged: ObjectWillChangePublisher = .init()
 
-        private func getValueFromViewModel(_ liveViewModel: LiveViewModel, bindingName: String) throws -> Value {
-            guard let defaultPayload = liveViewModel.bindingValues[bindingName] else {
-                throw LiveBindingError.missingDefaultPayload(bindingName)
-            }
-            // todo: if decoding fails, what should happen?
-            let value = try Value(from: FragmentDecoder(data: defaultPayload))
-            mode = .local(value)
-            return value
-        }
+        var valueCancellable: AnyCancellable?
+        var cancellable: AnyCancellable?
 
-        enum Mode {
-            case uninitialized
-            case needsUpdateFromViewModel
-            case local(Value)
+        func bind(to model: LiveViewModel, bindingName: String?, debounce: Double) {
+            if let bindingName {
+                if valueCancellable == nil && cancellable == nil,
+                   let defaultValue = model.bindingValues[bindingName]
+                {
+                    let decoder = FragmentDecoder(data: defaultValue)
+                    value = try! Value(from: decoder)
+                }
+                // Watch for local changes to the value.
+                valueCancellable = self.localValueChanged
+                    .debounce(for: .init(debounce), scheduler: RunLoop.current)
+                    .sink { [weak self, weak model] _ in
+                        guard let value = self?.value else { return }
+                        let encoder = FragmentEncoder()
+                        try! value.encode(to: encoder)
+                        guard let encodedValue = encoder.unwrap()
+                        else { return }
+                        model?.setBinding(bindingName, to: encodedValue)
+                    }
+                // Watch for changes from the server.
+                cancellable = model.bindingUpdatedByServer
+                    .filter({ $0.0 == bindingName })
+                    .sink(receiveValue: { [weak self] newValue in
+                        let decoder = FragmentDecoder(data: newValue.1)
+                        self?.value = try! Value(from: decoder)
+                        self?.objectWillChange.send()
+                    })
+            } else {
+                valueCancellable = nil
+                cancellable = nil
+            }
         }
     }
 }

Sources/LiveViewNative/Registries/CustomRegistry.swift

@@ -135,6 +135,11 @@ public protocol CustomRegistry<Root> {
     /// - Parameter error: The error of the view is reporting.
     @ViewBuilder
     static func errorView(for error: Error) -> ErrorView
+    
+    static func setBindingValue(_ value: Any, forKey key: String, in scope: String?) throws
+    static func bindingValue(forKey key: String, in scope: String?) -> Any?
+    static var globalBindings: Set<String> { get }
+    static func registerGlobalBinding(_ key: String)
 }
 
 extension CustomRegistry where LoadingView == Never {
@@ -151,6 +156,21 @@ extension CustomRegistry where ErrorView == Never {
     }
 }
 
+extension CustomRegistry {
+    public static func setBindingValue(_ value: Any, forKey key: String, in scope: String?) throws {
+        UserDefaults(suiteName: scope)?.setValue(value, forKey: key)
+    }
+    public static func bindingValue(forKey key: String, in scope: String?) -> Any? {
+        UserDefaults(suiteName: scope)?.value(forKey: key)
+    }
+    public static var globalBindings: Set<String> {
+        Set(UserDefaults.standard.stringArray(forKey: "_lvn_global_bindings") ?? [])
+    }
+    public static func registerGlobalBinding(_ key: String) {
+        UserDefaults.standard.setValue(Array<String>(globalBindings.union([key])), forKey: "_lvn_global_bindings")
+    }
+}
+
 /// The empty registry is the default ``CustomRegistry`` implementation that does not provide any views or modifiers.
 public struct EmptyRegistry {
 }

Sources/LiveViewNative/ViewModel.swift

@@ -7,6 +7,7 @@
 
 import Foundation
 import Combine
+import SwiftUI
 import LiveViewNativeCore
 
 /// The working-copy data model for a ``LiveView``.
@@ -16,10 +17,40 @@ public class LiveViewModel: ObservableObject {
     private var forms = [String: FormModel]()
     var cachedNavigationTitle: NavigationTitleModifier?
 
+    private(set) var bindings = [String: NativeBinding]()
+    private(set) var bindingScope: String?
+    
     private(set) var bindingValues = [String: Any]()
     let bindingUpdatedByServer = PassthroughSubject<(String, Any), Never>()
     let bindingUpdatedByClient = PassthroughSubject<(String, Any), Never>()
 
+    let bindingValue: (String, String?) -> Any?
+    let setBindingValue: (Any, String, String?) throws -> ()
+    let globalBindings: () -> Set<String>
+    let registerGlobalBinding: (String) -> ()
+    
+    init(
+        bindingValue: @escaping (String, String?) -> Any?,
+        setBindingValue: @escaping (Any, String, String?) throws -> (),
+        globalBindings: @escaping () -> Set<String>,
+        registerGlobalBinding: @escaping (String) -> ()
+    ) {
+        self.bindingValue = bindingValue
+        self.setBindingValue = setBindingValue
+        self.globalBindings = globalBindings
+        self.registerGlobalBinding = registerGlobalBinding
+    }
+    
+    struct NativeBinding {
+        let persist: PersistenceMode
+        
+        enum PersistenceMode: String {
+            case scoped
+            case global
+            case none
+        }
+    }
+    
     /// Get or create a ``FormModel`` for the given `<live-form>`.
     ///
     /// - Important: The element parameter must be the form element. To get the form model for an element within a form, use the ``LiveContext`` or the `\.formModel` environment value.
@@ -51,15 +82,69 @@ public class LiveViewModel: ObservableObject {
     }
 
     func updateBindings(payload: Payload) {
-        for (key, value) in payload {
-            bindingValues[key] = value
-            bindingUpdatedByServer.send((key, value))
+        if let data = payload["data"] as? [String:Any] {
+            let animation = (payload["animation"] as? [String:Any])
+                .flatMap({ try? JSONSerialization.data(withJSONObject: $0) })
+                .flatMap({ try? makeJSONDecoder().decode(Animation.self, from: $0) })
+            withAnimation(animation) {
+                for (key, value) in data {
+                    bindingValues[key] = value
+                    bindingUpdatedByServer.send((key, value))
+                    storeBinding(key, value: value)
+                }
+            }
         }
     }
 
     func setBinding(_ name: String, to encodedValue: Any) {
         bindingValues[name] = encodedValue
         bindingUpdatedByClient.send((name, encodedValue))
+        storeBinding(name, value: encodedValue)
+    }
+    
+    func storeBinding(_ key: String, value: Any) {
+        if let options = bindings[key] {
+            switch options.persist {
+            case .scoped:
+                try? setBindingValue(value, key, self.bindingScope)
+            case .global:
+                try? setBindingValue(value, key, nil)
+            case .none:
+                break
+            }
+        }
+    }
+    
+    func initBindings(payload: Payload) {
+        self.bindingScope = payload["scope"] as? String
+        for (key, options) in (payload["bindings"] as? [String:[String:Any]] ?? [:]) {
+            let binding = NativeBinding(
+                persist: (options["persist"] as? String).flatMap(NativeBinding.PersistenceMode.init(rawValue:)) ?? .none
+            )
+            self.bindings[key] = binding
+            
+            let defaultValue = options["default"]
+            
+            switch binding.persist {
+            case .scoped:
+                if let value = bindingValue(key, self.bindingScope) {
+                    self.bindingValues[key] = value
+                    setBinding(key, to: value)
+                } else {
+                    self.bindingValues[key] = defaultValue
+                }
+            case .global:
+                registerGlobalBinding(key)
+                if let value = bindingValue(key, nil) {
+                    self.bindingValues[key] = value
+                    setBinding(key, to: value)
+                } else {
+                    self.bindingValues[key] = defaultValue
+                }
+            case .none:
+                self.bindingValues[key] = defaultValue
+            }
+        }
     }
 }
 

Tests/RenderingTests/assertMatch.swift

@@ -100,7 +100,9 @@ extension XCTestCase {
             document[document.root()].children(),
             coordinator: session.rootCoordinator,
             url: session.url
-        ).environment(\.coordinatorEnvironment, CoordinatorEnvironment(session.rootCoordinator, document: document))
+        )
+            .environment(\.coordinatorEnvironment, CoordinatorEnvironment(session.rootCoordinator, document: document))
+            .environmentObject(LiveViewModel(bindingValue: EmptyRegistry.bindingValue, setBindingValue: EmptyRegistry.setBindingValue, globalBindings: { EmptyRegistry.globalBindings }, registerGlobalBinding: EmptyRegistry.registerGlobalBinding))
 
         let modifyViewForRender: (any View) -> any View = {
             if useDrawingGroup {