Implement scene preferences system (#325)

* add scene preferences

* use implicit memberwise initializer for `[Scene]PreferenceValues`

* make `Commands.overlayed(with:)` `consuming`

* fix `AlertScene`

* documentation and style fixups

---------

Co-authored-by: stackotter <[email protected]>

Author: kaascevich

Sources/SwiftCrossUI/App.swift

@@ -122,7 +122,7 @@ extension App {
         let _app = _App(app)
         _forceRefresh = {
             app.backend.runInMainThread {
-                _app.forceRefresh()
+                _app.refreshSceneGraph()
             }
         }
         _app.run()

Sources/SwiftCrossUI/Scenes/AlertScene.swift

@@ -53,7 +53,7 @@ public final class AlertSceneNode: SceneGraphNode {
         _ newScene: AlertScene?,
         backend: Backend,
         environment: EnvironmentValues
-    ) {
+    ) -> SceneUpdateResult {
         if let newScene {
             self.scene = newScene
         }
@@ -77,5 +77,7 @@ public final class AlertSceneNode: SceneGraphNode {
             backend.dismissAlert(alert as! Backend.Alert, window: nil)
             self.alert = nil
         }
+
+        return .leafScene()
     }
 }

Sources/SwiftCrossUI/Scenes/Commands.swift

@@ -7,32 +7,31 @@ public struct Commands: Sendable {
         self.menus = menus
     }
 
-    public func overlayed(with newCommands: Commands) -> Commands {
+    public consuming func overlayed(with newCommands: Commands) -> Commands {
         var newMenusByName: [String: Int] = [:]
         for (i, menu) in newCommands.menus.enumerated() {
             newMenusByName[menu.name] = i
         }
 
-        var commands = self
         for (i, menu) in menus.enumerated() {
             guard let newMenuIndex = newMenusByName[menu.name] else {
                 continue
             }
-            commands.menus[i] = CommandMenu(
+            menus[i] = CommandMenu(
                 name: menu.name,
                 content: menu.content + newCommands.menus[newMenuIndex].content
             )
         }
 
-        let existingMenuNames = Set(commands.menus.map(\.name))
+        let existingMenuNames = Set(menus.map(\.name))
         for newMenu in newCommands.menus {
             guard !existingMenuNames.contains(newMenu.name) else {
                 continue
             }
-            commands.menus.append(newMenu)
+            menus.append(newMenu)
         }
 
-        return commands
+        return self
     }
 
     /// Resolves the menus to a representation used by backends.

…SwiftCrossUI/Scenes/SceneGraphNode.swift …rossUI/Scenes/Graph/SceneGraphNode.swiftSources/SwiftCrossUI/Scenes/SceneGraphNode.swift renamed to Sources/SwiftCrossUI/Scenes/Graph/SceneGraphNode.swift Sources/SwiftCrossUI/Scenes/SceneGraphNode.swift renamed to Sources/SwiftCrossUI/Scenes/Graph/SceneGraphNode.swift

@@ -23,9 +23,10 @@ public protocol SceneGraphNode: AnyObject {
     ///   - newScene: The new recomputed scene if the update is due to being recomputed.
     ///   - backend: The backend to use.
     ///   - environment: The current root-level environment.
+    /// - Returns: The result of updating the scene.
     func update<Backend: AppBackend>(
         _ newScene: NodeScene?,
         backend: Backend,
         environment: EnvironmentValues
-    )
+    ) -> SceneUpdateResult
 }

Sources/SwiftCrossUI/Scenes/Graph/ScenePreferenceValues.swift

@@ -0,0 +1,14 @@
+/// A scene's preferences. Propagated up the scene hierarchy automatically.
+public struct ScenePreferenceValues: Sendable {
+    /// The default preferences.
+    public static let `default` = ScenePreferenceValues(commands: .empty)
+
+    /// The commands to be shown by the app.
+    public var commands: Commands
+}
+
+extension ScenePreferenceValues {
+    init(merging children: [ScenePreferenceValues]) {
+        commands = children.map(\.commands).reduce(.empty) { $0.overlayed(with: $1) }
+    }
+}

Sources/SwiftCrossUI/Scenes/Graph/SceneUpdateResult.swift

@@ -0,0 +1,21 @@
+/// The result of updating a scene.
+public struct SceneUpdateResult: Sendable {
+    /// The preference values produced by the scene and its children.
+    public var preferences: ScenePreferenceValues
+
+    public init(preferences: ScenePreferenceValues) {
+        self.preferences = preferences
+    }
+
+    /// Creates an update result by combining the preference values of a scene's
+    /// children.
+    public init(childResults: [SceneUpdateResult]) {
+        preferences = ScenePreferenceValues(merging: childResults.map(\.preferences))
+    }
+
+    /// Creates the layout result of a leaf scene (one with no children and no
+    /// special preference behaviour). Uses ``ScenePreferenceValues/default``.
+    public static func leafScene() -> Self {
+        SceneUpdateResult(preferences: .default)
+    }
+}

Sources/SwiftCrossUI/Scenes/Modifiers/CommandsModifier.swift

@@ -1,6 +1,6 @@
 extension Scene {
     public func commands(@CommandsBuilder _ commands: () -> Commands) -> some Scene {
-        CommandsModifier(content: self, newCommands: commands())
+        CommandsModifier(content: self, commands: commands())
     }
 }
 
@@ -10,23 +10,25 @@ struct CommandsModifier<Content: Scene>: Scene {
     var content: Content
     var commands: Commands
 
-    init(content: Content, newCommands: Commands) {
+    init(content: Content, commands: Commands) {
         self.content = content
-        self.commands = content.commands.overlayed(with: newCommands)
+        self.commands = commands
     }
 }
 
 final class CommandsModifierNode<Content: Scene>: SceneGraphNode {
     typealias NodeScene = CommandsModifier<Content>
 
+    var commands: Commands
     var contentNode: Content.Node
 
     init<Backend: AppBackend>(
         from scene: NodeScene,
         backend: Backend,
         environment: EnvironmentValues
     ) {
-        contentNode = Content.Node(
+        self.commands = scene.commands
+        self.contentNode = Content.Node(
             from: scene.content,
             backend: backend,
             environment: environment
@@ -37,11 +39,17 @@ final class CommandsModifierNode<Content: Scene>: SceneGraphNode {
         _ newScene: NodeScene?,
         backend: Backend,
         environment: EnvironmentValues
-    ) {
-        contentNode.update(
+    ) -> SceneUpdateResult {
+        if let newScene {
+            self.commands = newScene.commands
+        }
+
+        var result = contentNode.update(
             newScene?.content,
             backend: backend,
             environment: environment
         )
+        result.preferences.commands = result.preferences.commands.overlayed(with: commands)
+        return result
     }
 }

Sources/SwiftCrossUI/Scenes/Modifiers/SceneEnvironmentModifier.swift

@@ -36,8 +36,6 @@ struct SceneEnvironmentModifier<Content: Scene>: Scene {
     var content: Content
     var modification: (EnvironmentValues) -> EnvironmentValues
 
-    var commands: Commands { content.commands }
-
     init(
         _ content: Content,
         modification: @escaping (EnvironmentValues) -> EnvironmentValues
@@ -59,7 +57,7 @@ final class SceneEnvironmentModifierNode<Content: Scene>: SceneGraphNode {
         environment: EnvironmentValues
     ) {
         self.modification = scene.modification
-        contentNode = Content.Node(
+        self.contentNode = Content.Node(
             from: scene.content,
             backend: backend,
             environment: modification(environment)
@@ -70,12 +68,12 @@ final class SceneEnvironmentModifierNode<Content: Scene>: SceneGraphNode {
         _ newScene: NodeScene?,
         backend: Backend,
         environment: EnvironmentValues
-    ) {
+    ) -> SceneUpdateResult {
         if let newScene {
             self.modification = newScene.modification
         }
 
-        contentNode.update(
+        return contentNode.update(
             newScene?.content,
             backend: backend,
             environment: modification(environment)

Sources/SwiftCrossUI/Scenes/Scene.swift

@@ -6,7 +6,4 @@
 public protocol Scene {
     /// The node type used to manage this scene in the scene graph.
     associatedtype Node: SceneGraphNode where Node.NodeScene == Self
-
-    /// The commands to be propagated up from the scene.
-    var commands: Commands { get }
 }