LoadableView: add support for viewDidLoadActionID

When loading views dynamically the client needs to receive a callback when the view loads in order to be able to access the subviews/controls. Setting a different json value for LoadableView does not load it synchronously in-place so there was a race condition to access the load subviews.
The clients can now declare viewDidLoadActionID in LoadableView json and register a callback for that ID to get their action handler called when the loaded view is ready for access.

Author: abra-code

ActionUI/Common/FileLoadableView.swift

@@ -8,20 +8,25 @@ import SwiftUI
 // View for synchronous file-based loading (local file or bundle resource)
 @MainActor
 public struct FileLoadableView: SwiftUI.View {
+    // Static dedup tracking — avoids using @Published ViewModel.states which would trigger re-renders
+    private static var loadedSources: [String: String] = [:]
+
     let fileURL: URL
     let windowUUID: String
     let isContentView: Bool
     let parentID: Int
+    let viewDidLoadActionID: String?
     let logger: any ActionUILogger
 
     private let element: ActionUIElement?
     private let error: Error?
 
-    public init(fileURL: URL, windowUUID: String, isContentView: Bool, parentID: Int = 0, logger: any ActionUILogger) {
+    public init(fileURL: URL, windowUUID: String, isContentView: Bool, parentID: Int = 0, viewDidLoadActionID: String? = nil, logger: any ActionUILogger) {
         self.fileURL = fileURL
         self.windowUUID = windowUUID
         self.isContentView = isContentView
         self.parentID = parentID
+        self.viewDidLoadActionID = viewDidLoadActionID
         self.logger = logger
 
         // Perform synchronous loading in init
@@ -36,13 +41,22 @@ public struct FileLoadableView: SwiftUI.View {
             }
             logger.log("Successfully loaded \(format) for LoadableView from file \(fileURL)", .debug)
             self.error = nil
+            // Defer fireViewDidLoad to after current body evaluation completes
+            // Uses static dedup so it only fires once per unique source
+            let capturedFileURL = fileURL
+            let capturedWindowUUID = windowUUID
+            let capturedParentID = parentID
+            let capturedActionID = viewDidLoadActionID
+            Task { @MainActor in
+                Self.fireViewDidLoad(fileURL: capturedFileURL, windowUUID: capturedWindowUUID, parentID: capturedParentID, viewDidLoadActionID: capturedActionID)
+            }
         } catch {
             self.element = nil
             self.error = error
             logger.log("Failed to load description for LoadableView from file \(fileURL): \(error)", .error)
         }
     }
-    
+
     public var body: some SwiftUI.View {
         if let error = error {
             SwiftUI.Text("Failed to load view: \(error.localizedDescription)")
@@ -55,4 +69,15 @@ public struct FileLoadableView: SwiftUI.View {
             SwiftUI.Text("No content loaded")
         }
     }
+
+    private static func fireViewDidLoad(fileURL: URL, windowUUID: String, parentID: Int, viewDidLoadActionID: String?) {
+        guard let actionID = viewDidLoadActionID else { return }
+        guard ActionUIModel.shared.windowModels[windowUUID]?.viewModels[parentID] != nil else { return }
+
+        let key = "\(windowUUID)_\(parentID)"
+        let source = fileURL.absoluteString
+        guard loadedSources[key] != source else { return }
+        loadedSources[key] = source
+        ActionUIModel.shared.actionHandler(actionID, windowUUID: windowUUID, viewID: parentID, viewPartID: 0)
+    }
 }

ActionUI/Common/RemoteLoadableView.swift

@@ -8,23 +8,28 @@ import SwiftUI
 // View for remote asynchronous loading
 @MainActor
 public struct RemoteLoadableView: SwiftUI.View {
+    // Static dedup tracking — avoids using @Published ViewModel.states which would trigger re-renders
+    private static var loadedSources: [String: String] = [:]
+
     let url: URL
     let windowUUID: String
     let isContentView: Bool
     let parentID: Int
+    let viewDidLoadActionID: String?
     let logger: any ActionUILogger
 
     @State private var element: ActionUIElement?
     @State private var error: Error?
 
-    public init(url: URL, windowUUID: String, isContentView: Bool, parentID: Int = 0, logger: any ActionUILogger) {
+    public init(url: URL, windowUUID: String, isContentView: Bool, parentID: Int = 0, viewDidLoadActionID: String? = nil, logger: any ActionUILogger) {
         self.url = url
         self.windowUUID = windowUUID
         self.isContentView = isContentView
         self.parentID = parentID
+        self.viewDidLoadActionID = viewDidLoadActionID
         self.logger = logger
     }
-    
+
     public var body: some SwiftUI.View {
         if let error = error {
             SwiftUI.Text("Failed to load view: \(error.localizedDescription)")
@@ -41,7 +46,7 @@ public struct RemoteLoadableView: SwiftUI.View {
                             var request = URLRequest(url: url)
                             request.cachePolicy = .reloadRevalidatingCacheData // Balances freshness and performance
                             let (data, _) = try await URLSession.shared.data(for: request)
-                            
+
                             // Determine format based on URL extension
                             let format = url.pathExtension.lowercased() == "plist" ? "plist" : "json"
                             logger.log("Determined format '\(format)' for remote URL \(url)", .debug)
@@ -51,6 +56,7 @@ public struct RemoteLoadableView: SwiftUI.View {
                                 element = try ActionUIModel.shared.loadSubViewDescription(from: data, format: format, windowUUID: windowUUID, parentID: parentID)
                             }
                             logger.log("Successfully loaded \(format) for LoadableView from remote \(url)", .debug)
+                            fireViewDidLoad()
                         } catch {
                             self.error = error
                             logger.log("Failed to load remote description for LoadableView from \(url): \(error)", .error)
@@ -59,4 +65,15 @@ public struct RemoteLoadableView: SwiftUI.View {
                 }
         }
     }
+
+    private func fireViewDidLoad() {
+        guard let actionID = viewDidLoadActionID else { return }
+        guard ActionUIModel.shared.windowModels[windowUUID]?.viewModels[parentID] != nil else { return }
+
+        let key = "\(windowUUID)_\(parentID)"
+        let source = url.absoluteString
+        guard Self.loadedSources[key] != source else { return }
+        Self.loadedSources[key] = source
+        ActionUIModel.shared.actionHandler(actionID, windowUUID: windowUUID, viewID: parentID, viewPartID: 0)
+    }
 }

ActionUI/Views/LoadableView.swift

@@ -7,7 +7,8 @@
    "properties": {
      "url": "https://example.com/view.json", // Optional: String URL to remote JSON or binary plist (http://, https://)
      "filePath": "/path/to/view.json",       // Optional: String absolute path to local JSON or binary plist
-     "name": "HelloWorld.json"               // Optional: String name of JSON or binary plist resource in app bundle
+     "name": "HelloWorld.json",              // Optional: String name of JSON or binary plist resource in app bundle
+     "viewDidLoadActionID": "view.loaded"    // Optional: String action triggered once after a new sub-view is loaded. Not re-triggered on SwiftUI body rebuilds for the same source.
    }
    // Note: Requires exactly one of "url", "filePath", or "name" to be valid. Loads JSON or binary plist, determined by .json or .plist extension, parses into ActionUIElementBase using ActionUIModel.loadDescription, and renders ActionUIView. Remote "url" loads asynchronously with ProgressView; local "filePath" or bundle "name" loads synchronously in init. Assumes unique IDs in loaded description to avoid conflicts with existing windowModels. Baseline View properties (padding, hidden, foregroundColor, font, background, frame, opacity, cornerRadius, actionID, disabled) and additional View protocol modifiers are inherited and applied via ActionUIRegistry.shared.applyViewModifiers(to: baseView, properties: element.properties).
    // Note: Invalid sources or unsupported extensions will result in error display. The source (url/filePath/name) is the designated value (valueType: String.self), settable via ActionUIModel.setElementValue, with heuristics: http:// or https:// for URL, file:// or / for filePath, else bundle name.
@@ -57,8 +58,9 @@ struct LoadableView: ActionUIViewConstruction {
     }
 
     static var buildView: (any ActionUIElementBase, ViewModel, String, [String: Any], any ActionUILogger) -> any SwiftUI.View = { element, model, windowUUID, properties, logger in
-        
+
         let isContentView = false
+        let viewDidLoadActionID = properties["viewDidLoadActionID"] as? String
         // Use model.value if set (heuristics to interpret), else fallback to validated properties
         guard let value = Self.initialValue(model) as? String, !value.isEmpty else {
             logger.log("No valid source for LoadableView, displaying error SwiftUI.Text", .warning)
@@ -72,7 +74,7 @@ struct LoadableView: ActionUIViewConstruction {
                 return SwiftUI.Text("Invalid URL: \(value)")
             }
             logger.log("Interpreting value as remote URL: \(value)", .debug)
-            return RemoteLoadableView(url: url, windowUUID: windowUUID, isContentView: isContentView, parentID: element.id, logger: logger)
+            return RemoteLoadableView(url: url, windowUUID: windowUUID, isContentView: isContentView, parentID: element.id, viewDidLoadActionID: viewDidLoadActionID, logger: logger)
         } else {
             var fileURL: URL
             if value.lowercased().hasPrefix("file://") {
@@ -97,7 +99,7 @@ struct LoadableView: ActionUIViewConstruction {
                 fileURL = url
                 logger.log("Interpreting value as bundle name: \(value)", .debug)
             }
-            return FileLoadableView(fileURL: fileURL, windowUUID: windowUUID, isContentView: isContentView, parentID: element.id, logger: logger)
+            return FileLoadableView(fileURL: fileURL, windowUUID: windowUUID, isContentView: isContentView, parentID: element.id, viewDidLoadActionID: viewDidLoadActionID, logger: logger)
         }
     }
 

ActionUITests/Views/LoadableViewTests.swift

@@ -284,4 +284,152 @@ final class LoadableViewTests: XCTestCase {
         XCTAssertNotNil(windowModel.viewModels[1], "Root VStack model should be preserved after sub-view swap")
         XCTAssertNotNil(windowModel.viewModels[100], "LoadableView model should be preserved after sub-view swap")
     }
+
+    // MARK: - viewDidLoadActionID tests
+
+    /// Helper: loads a root window with a LoadableView that has viewDidLoadActionID set.
+    private func loadRootWithViewDidLoadAction() throws -> WindowModel {
+        let rootJSON = """
+        {
+            "id": 1,
+            "type": "VStack",
+            "properties": {},
+            "children": [
+                { "id": 100, "type": "LoadableView", "properties": { "filePath": "/tmp/panel.json", "viewDidLoadActionID": "params.loaded" } }
+            ]
+        }
+        """
+        let data = rootJSON.data(using: .utf8)!
+        _ = try ActionUIModel.shared.loadDescription(from: data, format: "json", windowUUID: windowUUID)
+        return ActionUIModel.shared.windowModels[windowUUID]!
+    }
+
+    /// Tracks dedup state for simulateFireViewDidLoad, mirroring the static dict in FileLoadableView/RemoteLoadableView.
+    private var simulatedLoadedSources: [String: String] = [:]
+
+    /// Simulates the fireViewDidLoad logic used by FileLoadableView/RemoteLoadableView.
+    /// This avoids needing SwiftUI view instantiation in unit tests.
+    private func simulateFireViewDidLoad(parentID: Int, source: String, actionID: String) {
+        guard !actionID.isEmpty else { return }
+        guard ActionUIModel.shared.windowModels[windowUUID]?.viewModels[parentID] != nil else { return }
+
+        let key = "\(windowUUID!)_\(parentID)"
+        guard simulatedLoadedSources[key] != source else { return }
+        simulatedLoadedSources[key] = source
+        ActionUIModel.shared.actionHandler(actionID, windowUUID: windowUUID, viewID: parentID, viewPartID: 0)
+    }
+
+    func testViewDidLoadActionIDPropertyValidation() throws {
+        let windowModel = try loadRootWithViewDidLoadAction()
+        let viewModel = windowModel.viewModels[100]!
+        XCTAssertEqual(viewModel.validatedProperties["viewDidLoadActionID"] as? String, "params.loaded",
+                       "viewDidLoadActionID should be preserved in validated properties")
+    }
+
+    func testViewDidLoadFiresOnFirstLoad() throws {
+        let windowModel = try loadRootWithViewDidLoadAction()
+        let parentID = 100
+
+        // Load sub-view content
+        let subData = subViewJSON(rootID: 200, childIDs: [201])
+        _ = try windowModel.loadSubViewDescription(from: subData, format: "json", parentID: parentID)
+
+        // Track action handler calls
+        var firedActions: [(String, Int)] = []
+        ActionUIModel.shared.setDefaultActionHandler { actionID, _, viewID, _, _ in
+            firedActions.append((actionID, viewID))
+        }
+
+        // Simulate fireViewDidLoad
+        simulateFireViewDidLoad(parentID: parentID, source: "file:///tmp/panel.json", actionID: "params.loaded")
+
+        XCTAssertEqual(firedActions.count, 1, "Action should fire once")
+        XCTAssertEqual(firedActions[0].0, "params.loaded", "Action ID should match")
+        XCTAssertEqual(firedActions[0].1, parentID, "View ID should be the LoadableView's ID")
+    }
+
+    func testViewDidLoadDoesNotReFireForSameSource() throws {
+        let windowModel = try loadRootWithViewDidLoadAction()
+        let parentID = 100
+
+        let subData = subViewJSON(rootID: 200, childIDs: [201])
+        _ = try windowModel.loadSubViewDescription(from: subData, format: "json", parentID: parentID)
+
+        var fireCount = 0
+        ActionUIModel.shared.setDefaultActionHandler { _, _, _, _, _ in
+            fireCount += 1
+        }
+
+        // First call should fire
+        simulateFireViewDidLoad(parentID: parentID, source: "file:///tmp/panel.json", actionID: "params.loaded")
+        XCTAssertEqual(fireCount, 1, "Should fire on first call")
+
+        // Second call with same source should not fire (simulates SwiftUI body rebuild)
+        simulateFireViewDidLoad(parentID: parentID, source: "file:///tmp/panel.json", actionID: "params.loaded")
+        XCTAssertEqual(fireCount, 1, "Should not re-fire for the same source")
+    }
+
+    func testViewDidLoadFiresAgainForNewSource() throws {
+        let windowModel = try loadRootWithViewDidLoadAction()
+        let parentID = 100
+
+        var firedSources: [String] = []
+        ActionUIModel.shared.setDefaultActionHandler { actionID, _, _, _, _ in
+            firedSources.append(actionID)
+        }
+
+        // First source
+        let subData1 = subViewJSON(rootID: 200, childIDs: [201])
+        _ = try windowModel.loadSubViewDescription(from: subData1, format: "json", parentID: parentID)
+        simulateFireViewDidLoad(parentID: parentID, source: "file:///tmp/brightness.json", actionID: "params.loaded")
+
+        // Replace with new source
+        let subData2 = subViewJSON(rootID: 300, childIDs: [301])
+        _ = try windowModel.loadSubViewDescription(from: subData2, format: "json", parentID: parentID)
+        simulateFireViewDidLoad(parentID: parentID, source: "file:///tmp/contrast.json", actionID: "params.loaded")
+
+        XCTAssertEqual(firedSources.count, 2, "Should fire for each new source")
+    }
+
+    func testViewDidLoadNotFiredWithoutActionID() throws {
+        // Use the helper without viewDidLoadActionID
+        let windowModel = try loadRootWithLoadableView()
+        let parentID = 100
+
+        let subData = subViewJSON(rootID: 200, childIDs: [201])
+        _ = try windowModel.loadSubViewDescription(from: subData, format: "json", parentID: parentID)
+
+        var fireCount = 0
+        ActionUIModel.shared.setDefaultActionHandler { _, _, _, _, _ in
+            fireCount += 1
+        }
+
+        // Empty actionID should not fire (mirrors nil viewDidLoadActionID in real code)
+        simulateFireViewDidLoad(parentID: parentID, source: "file:///tmp/panel.json", actionID: "")
+        XCTAssertEqual(fireCount, 0, "Should not fire when actionID is empty")
+    }
+
+    func testFullReloadClearsViewModels() throws {
+        let windowModel = try loadRootWithViewDidLoadAction()
+        let parentID = 100
+
+        let subData = subViewJSON(rootID: 200, childIDs: [201])
+        _ = try windowModel.loadSubViewDescription(from: subData, format: "json", parentID: parentID)
+
+        var fireCount = 0
+        ActionUIModel.shared.setDefaultActionHandler { _, _, _, _, _ in
+            fireCount += 1
+        }
+
+        simulateFireViewDidLoad(parentID: parentID, source: "file:///tmp/panel.json", actionID: "params.loaded")
+        XCTAssertEqual(fireCount, 1)
+
+        // Full window reload should clear all ViewModels
+        let rootJSON = """
+        { "id": 1, "type": "Text", "properties": { "text": "fresh" } }
+        """
+        _ = try windowModel.loadDescription(from: rootJSON.data(using: .utf8)!, format: "json")
+
+        XCTAssertNil(windowModel.viewModels[parentID], "Old LoadableView ViewModel should be gone after full reload")
+    }
 }