Workaround iOS issue calling widget timelines several times (#3414)

<!-- Thank you for submitting a Pull Request and helping to improve Home
Assistant. Please complete the following sections to help the processing
and review of your changes. Please do not delete anything from this
template. -->

## Summary
<!-- Provide a brief summary of the changes you have made and most
importantly what they aim to achieve -->
There is a long term bug in iOS which calls widget timelines several
times even though once would be enough to render the widget. Since
apparently Apple is not giving attention to that and out custom widgets
make data calls, this PRs ads a small cache to prevent unecessary data
calls.

## Screenshots
<!-- If this is a user-facing change not in the frontend, please include
screenshots in light and dark mode. -->

## Link to pull request in Documentation repository
<!-- Pull requests that add, change or remove functionality must have a
corresponding pull request in the Companion App Documentation repository
(https://github.com/home-assistant/companion.home-assistant). Please add
the number of this pull request after the "#" -->
Documentation: home-assistant/companion.home-assistant#

## Any other notes
<!-- If there is any other information of note, like if this Pull
Request is part of a bigger change, please include it here. -->

Author: bgoncal

Sources/App/Scenes/WebViewSceneDelegate.swift

@@ -127,6 +127,15 @@ final class WebViewSceneDelegate: NSObject, UIWindowSceneDelegate {
         })
         Current.appDatabaseUpdater.update()
         Current.panelsUpdater.update()
+
+        let widgetsCacheFile = AppConstants.widgetsCacheURL
+
+        // Clean up widgets cache file
+        do {
+            try FileManager.default.removeItem(at: widgetsCacheFile)
+        } catch {
+            Current.Log.error("Failed to remove widgets cache file: \(error)")
+        }
     }
 
     func windowScene(

Sources/Extensions/Widgets/Custom/AppIntents/CustomWidgetToggleAppIntent.swift

@@ -47,14 +47,6 @@ struct CustomWidgetToggleAppIntent: AppIntent {
             }
         }
         _ = try await ResetAllCustomWidgetConfirmationAppIntent().perform()
-
-        /* Since several entities when toggled may not report the correct state right away
-         This is a workaround to refresh the widget a little later
-         In theory through push notification we could always ask the widget to update through
-         and automation/blueprint etc, but it's currently not reliable https://developer.apple.com/forums/thread/773852 */
-        DispatchQueue.main.asyncAfter(deadline: .now() + 2) {
-            WidgetCenter.shared.reloadTimelines(ofKind: WidgetsKind.custom.rawValue)
-        }
         return .result()
     }
 }

Sources/Extensions/Widgets/Custom/AppIntents/UpdateWidgetItemConfirmationStateAppIntent.swift

@@ -26,7 +26,7 @@ struct UpdateWidgetItemConfirmationStateAppIntent: AppIntent {
 
         if var widget = try CustomWidget.widgets()?.first(where: { $0.id == widgetId }),
            let magicItem = widget.items.first(where: { $0.serverUniqueId == serverUniqueId }) {
-            widget.itemsStates[magicItem.serverUniqueId] = .pendingConfirmation
+            widget.itemsStates = [magicItem.serverUniqueId: .pendingConfirmation]
             do {
                 try await Current.database.write { [widget] db in
                     try widget.update(db)

Sources/Extensions/Widgets/Custom/WidgetCustomTimelineProvider.swift

@@ -11,12 +11,18 @@ struct WidgetCustomEntry: TimelineEntry {
     var showLastUpdateTime: Bool
     var showStates: Bool
 
-    struct ItemState {
+    struct ItemState: Codable {
         let value: String
         let domainState: Domain.State?
     }
 }
 
+struct WidgetCustomItemStatesCache: Codable {
+    let widgetId: String
+    let cacheCreatedDate: Date
+    let states: [MagicItem: WidgetCustomEntry.ItemState]
+}
+
 @available(iOS 17, *)
 struct WidgetCustomTimelineProvider: AppIntentTimelineProvider {
     typealias Entry = WidgetCustomEntry
@@ -121,6 +127,16 @@ struct WidgetCustomTimelineProvider: AppIntentTimelineProvider {
             return [:]
         }
 
+        /* Cache states in local json
+         Necessary because there is a long term bug in widgets which triggers a reload of the timeline provider
+         several times instead of just once */
+        if let cache = getStatesCache(widgetId: widget.id), cache.cacheCreatedDate.timeIntervalSinceNow > -1 {
+            Current.Log.verbose("Widget custom states cache is still valid, returning cached states")
+            return cache.states
+        }
+
+        Current.Log.verbose("Widget custom has no valid cache, fetching states")
+
         let items = widget.items.filter {
             // No state needed for those domains
             ![.script, .scene, .inputButton].contains($0.domain)
@@ -151,8 +167,41 @@ struct WidgetCustomTimelineProvider: AppIntentTimelineProvider {
             }
         }
 
+        /* Cache states in local json
+         Necessary because there is a long term bug in widgets which triggers a reload of the timeline provider
+         several times instead of just once */
+        do {
+            let cache = WidgetCustomItemStatesCache(
+                widgetId: widget.id,
+                cacheCreatedDate: Date(),
+                states: states
+            )
+            let fileURL = AppConstants.widgetCachedStates(widgetId: widget.id)
+            let encodedStates = try JSONEncoder().encode(cache)
+            try encodedStates.write(to: fileURL)
+            Current.Log
+                .verbose("JSON saved successfully for widget custom cached states, file URL: \(fileURL.absoluteString)")
+        } catch {
+            Current.Log
+                .error("Failed to cache states in WidgetCustomTimelineProvider, error: \(error.localizedDescription)")
+        }
+
         return states
     }
+
+    private func getStatesCache(widgetId: String) -> WidgetCustomItemStatesCache? {
+        let fileURL = AppConstants.widgetCachedStates(widgetId: widgetId)
+        do {
+            let data = try Data(contentsOf: fileURL)
+            return try JSONDecoder().decode(WidgetCustomItemStatesCache.self, from: data)
+        } catch {
+            Current.Log
+                .error(
+                    "Failed to load states cache in WidgetCustomTimelineProvider, error: \(error.localizedDescription)"
+                )
+            return nil
+        }
+    }
 }
 
 enum WidgetCustomConstants {

Sources/Shared/Domain/Domain.swift

@@ -17,7 +17,7 @@ public enum Domain: String, CaseIterable {
     case person
     // TODO: Map more domains
 
-    public enum State: String {
+    public enum State: String, Codable {
         case locked
         case unlocked
         case jammed

Sources/Shared/Environment/AppConstants.swift

@@ -110,6 +110,26 @@ public enum AppConstants {
         return eventsURL
     }
 
+    public static var widgetsCacheURL: URL = {
+        let fileManager = FileManager.default
+        let directoryURL = Self.AppGroupContainer.appendingPathComponent("caches/widgets", isDirectory: true)
+        return directoryURL
+    }()
+
+    public static func widgetCachedStates(widgetId: String) -> URL {
+        let fileManager = FileManager.default
+        let directoryURL = Self.widgetsCacheURL
+        if !fileManager.fileExists(atPath: directoryURL.path) {
+            do {
+                try fileManager.createDirectory(at: directoryURL, withIntermediateDirectories: true)
+            } catch {
+                Current.Log.error("Failed to create Client Events file")
+            }
+        }
+        let eventsURL = directoryURL.appendingPathComponent("/widgetId-\(widgetId).json")
+        return eventsURL
+    }
+
     public static var watchMagicItemsInfo: URL {
         let fileManager = FileManager.default
         let directoryURL = Self.AppGroupContainer.appendingPathComponent("caches", isDirectory: true)