Update EnvironmentValues (#268)

* Update EnvironmentValues implementation

* Update Environment test case

* Update EnvironmentKey documentation

* Fix test case issue

Author: Kyle-Ye

Sources/OpenSwiftUI/Util/OpenSwiftUIGlue.swift

@@ -97,6 +97,7 @@ final public class OpenSwiftUIGlue2: CoreGlue2 {
     }
 
     override public final func configureDefaultEnvironment(_: inout EnvironmentValues) {
+        // TODO
     }
 
     override public final func makeRootView(base: AnyView, rootFocusScope: Namespace.ID) -> AnyView {

Sources/OpenSwiftUICore/Data/Environment/EnvironmentKey.swift

@@ -70,6 +70,20 @@ public protocol EnvironmentKey {
     /// The default value for the environment key.
     static var defaultValue: Value { get }
 
+    /// Compares two values of the environment key's associated type.
+    ///
+    /// This function determines if two values of this environment key's 
+    /// associated type should be considered equal. OpenSwiftUI uses this 
+    /// to determine when environment changes should trigger view updates.
+    ///
+    /// - Parameters:
+    ///   - lhs: The first value to compare.
+    ///   - rhs: The second value to compare.
+    /// - Returns: `true` if the values are considered equal; otherwise, `false`.
+    ///
+    /// The default implementation uses general value comparison for non-Equatable types.
+    /// Types conforming to `Equatable` receive an optimized implementation that uses
+    /// the `==` operator.
     static func _valuesEqual(_ lhs: Self.Value, _ rhs: Self.Value) -> Bool
 }
 
@@ -85,7 +99,42 @@ extension EnvironmentKey where Value: Equatable {
     }
 }
 
+/// A protocol that defines environment keys derived from other environment values.
+///
+/// Unlike standard `EnvironmentKey` that stores values directly, a `DerivedEnvironmentKey`
+/// calculates its value dynamically based on other environment values.
+///
+/// To implement a derived environment key:
+/// 1. Create a type that conforms to `DerivedEnvironmentKey`
+/// 2. Specify the `Value` type that must conform to `Equatable`
+/// 3. Implement the `value(in:)` method to compute the derived value
+///
+/// Example:
+///
+///     private struct MyDerivedKey: DerivedEnvironmentKey {
+///         typealias Value = String
+///
+///         static func value(in values: EnvironmentValues) -> String {
+///             return "\(values.someOtherValue) derived"
+///         }
+///     }
+///
+/// Then extend `EnvironmentValues` to access your derived value:
+///
+///     extension EnvironmentValues {
+///         var myDerivedValue: String {
+///             self[MyDerivedKey.self]
+///         }
+///     }
+///
 package protocol DerivedEnvironmentKey {
+    /// The associated type representing the type of the environment key's
+    /// value.
     associatedtype Value: Equatable
+    
+    /// Calculates the derived value based on the current environment values.
+    ///
+    /// - Parameter values: The current environment values.
+    /// - Returns: The derived value for this key.
     static func value(in: EnvironmentValues) -> Value
 }

Sources/OpenSwiftUICore/Data/Environment/EnvironmentValues.swift

@@ -3,7 +3,7 @@
 //  OpenSwiftUICore
 //
 //  Audited for iOS 18.0
-//  Status: TODO
+//  Status: Complete
 //  ID: 83E729E7BD00420AB79EFD8DF557072A (SwiftUI)
 //  ID: 0CBA6217BE011883F496E97230B6CF8F (SwiftUICore)
 
@@ -87,28 +87,92 @@ public struct EnvironmentValues: CustomStringConvertible {
     public init() {
         _plist = PropertyList()
         tracker = nil
-        // TODO: CoreGlue.shared
+        CoreGlue2.shared.configureDefaultEnvironment(&self)
     }
 
+    /// Creates an environment values instance with the specified property list.
+    ///
+    /// - Parameter plist: The property list to initialize the environment values with.
     package init(_ plist: PropertyList) {
         _plist = plist
         tracker = nil
     }
 
+    /// Creates an environment values instance with the specified property list and tracker.
+    ///
+    /// - Parameters:
+    ///   - plist: The property list to initialize the environment values with.
+    ///   - tracker: The tracker to monitor property list changes.
     package init(_ plist: PropertyList, tracker: PropertyList.Tracker) {
-        // FIXME
+        tracker.initializeValues(from: plist)
         self._plist = plist
         self.tracker = tracker
     }
 
-    // FIXME
+    /// The underlying property list that stores environment values.
     package var plist: PropertyList {
-        get { _plist }
+        get {
+            _plist
+        }
         set {
+            guard _plist.id != newValue.id else {
+                return
+            }
+            if let tracker {
+                tracker.invalidateAllValues(from: _plist, to: newValue)
+            }
             _plist = newValue
         }
     }
 
+    /// Returns a new environment values instance without a tracker.
+    ///
+    /// - Returns: An environment values instance with the same property list but no tracker.
+    package func removingTracker() -> EnvironmentValues {
+        EnvironmentValues(_plist)
+    }
+    
+    /// Adds dependencies from another tracker to this environment's tracker.
+    ///
+    /// - Parameter other: The tracker whose dependencies should be added.
+    package func addDependencies(from other: PropertyList.Tracker) {
+        guard let tracker else { return }
+        tracker.formUnion(other)
+    }
+    
+    /// Retrieves a value using a secondary lookup mechanism.
+    ///
+    /// - Parameter key: The lookup key type.
+    /// - Returns: The value associated with the key's primary type.
+    package func valueWithSecondaryLookup<Lookup>(_ key: Lookup.Type) -> Lookup.Primary.Value where Lookup: PropertyKeyLookup {
+        if let tracker {
+            tracker.valueWithSecondaryLookup(_plist, secondaryLookupHandler: key)
+        } else {
+            _plist.valueWithSecondaryLookup(key)
+        }
+    }
+    
+    /// Sets a value for the specified environment key.
+    ///
+    /// - Parameters:
+    ///   - value: The value to set.
+    ///   - key: The environment key type.
+    package mutating func setValue<K>(_ value: K.Value, for key: K.Type) where K: EnvironmentKey {
+        _set(value, for: key)
+    }
+    
+    private mutating func _set<K>(_ value: K.Value, for key: K.Type) where K: EnvironmentKey {
+        let oldPlist = _plist
+        _plist[EnvironmentPropertyKey<K>.self] = value
+        if let tracker {
+            tracker.invalidateValue(
+                for: EnvironmentPropertyKey<K>.self,
+                from: oldPlist,
+                to: plist
+            )
+        }
+    }
+
     /// Accesses the environment value associated with a custom key.
     ///
     /// Create custom environment values by defining a key
@@ -148,17 +212,17 @@ public struct EnvironmentValues: CustomStringConvertible {
             }
         }
         set {
-            _plist[EnvironmentPropertyKey<K>.self] = newValue
-            if let tracker {
-                tracker.invalidateValue(
-                    for: EnvironmentPropertyKey<K>.self,
-                    from: _plist,
-                    to: _plist
-                )
-            }
+            setValue(newValue, for: key)
         }
     }
 
+    /// Accesses the environment value associated with a derived environment key.
+    ///
+    /// Derived environment keys calculate their values based on other environment values.
+    /// This subscript provides read-only access to these derived values.
+    ///
+    /// - Parameter key: The derived environment key type.
+    /// - Returns: The value associated with the key.
     package subscript<K>(key: K.Type) -> K.Value where K: DerivedEnvironmentKey {
         if let tracker {
             tracker.derivedValue(_plist, for: DerivedEnvironmentPropertyKey<K>.self)
@@ -175,12 +239,25 @@ public struct EnvironmentValues: CustomStringConvertible {
 @available(*, unavailable)
 extension EnvironmentValues: Sendable {}
 
-private struct EnvironmentPropertyKey<EnvKey: EnvironmentKey>: PropertyKey {
-    static var defaultValue: EnvKey.Value { EnvKey.defaultValue }
+/// A property key that provides access to environment values.
+///
+/// This type bridges between the `EnvironmentKey` protocol and the internal `PropertyKey` system.
+private struct EnvironmentPropertyKey<Key>: PropertyKey where Key: EnvironmentKey {
+    /// The default value for this property key, obtained from the environment key.
+    static var defaultValue: Key.Value {
+        Key.defaultValue
+    }
 }
 
-private struct DerivedEnvironmentPropertyKey<EnvKey: DerivedEnvironmentKey>: DerivedPropertyKey {
-    static func value(in plist: PropertyList) -> EnvKey.Value {
-        EnvKey.value(in: EnvironmentValues(plist))
+/// A property key that provides access to derived environment values.
+///
+/// This type bridges between the `DerivedEnvironmentKey` protocol and the internal `DerivedPropertyKey` system.
+private struct DerivedEnvironmentPropertyKey<Key>: DerivedPropertyKey where Key: DerivedEnvironmentKey {
+    /// Calculates the derived value based on the current environment.
+    ///
+    /// - Parameter plist: The property list containing the current environment state.
+    /// - Returns: The calculated value for this derived key.
+    static func value(in plist: PropertyList) -> Key.Value {
+        Key.value(in: EnvironmentValues(plist))
     }
 }

Sources/OpenSwiftUITestsSupport/Data/EnvironmentKey+Test.swift

@@ -0,0 +1,39 @@
+//
+//  EnvironmentKey+Test.swift
+//  OpenSwiftUITestsSupport
+
+package import OpenSwiftUI
+
+package struct StringEnvironmentKey: EnvironmentKey {
+    package static var defaultValue: String { "" }
+}
+
+package struct IntEnvironmentKey: EnvironmentKey {
+    package static var defaultValue: Int { 0 }
+}
+
+package struct BoolEnvironmentKey: EnvironmentKey {
+    package static var defaultValue: Bool { false }
+}
+
+package struct DerivedStringEnvironmentKey: DerivedEnvironmentKey {
+    package static func value(in environment: EnvironmentValues) -> String {
+        "d:\(environment[StringEnvironmentKey.self])"
+    }
+}
+
+package struct OptionalStringEnvironmentKey: EnvironmentKey {
+    package static let defaultValue: String? = nil
+}
+
+package struct CustomStructEnvironmentKey: EnvironmentKey {
+    package struct CustomStruct {
+        package let value: Int
+        
+        package init(value: Int) {
+            self.value = value
+        }
+    }
+    
+    package static let defaultValue = CustomStruct(value: 100)
+}

Sources/OpenSwiftUITestsSupport/Data/PropertyList+Test.swift renamed to Sources/OpenSwiftUITestsSupport/Data/PropertyListKey+Test.swift

@@ -1,5 +1,5 @@
 //
-//  PropertyList+Test.swift
+//  PropertyListKey+Test.swift
 //  OpenSwiftUITestsSupport
 
 package import OpenSwiftUI

Tests/OpenSwiftUICoreTests/Data/Environment/EnvironmentKeyTests.swift

@@ -0,0 +1,57 @@
+//
+//  EnvironmentKeyTests.swift
+//  OpenSwiftUICoreTests
+
+import OpenSwiftUICore
+import OpenSwiftUITestsSupport
+import Testing
+
+struct EnvironmentKeyTests {
+    // MARK: - Default Value Tests
+    
+    @Test
+    func defaultValues() {
+        #expect(StringEnvironmentKey.defaultValue == "")
+        #expect(IntEnvironmentKey.defaultValue == 0)
+        #expect(OptionalStringEnvironmentKey.defaultValue == nil)
+        #expect(CustomStructEnvironmentKey.defaultValue.value == 100)
+    }
+    
+    // MARK: - Value Equality Tests
+    
+    @Test
+    func equatableValuesComparison() {
+        #expect(StringEnvironmentKey._valuesEqual("test", "test") == true)
+        #expect(StringEnvironmentKey._valuesEqual("test", "different") == false)
+        
+        #expect(IntEnvironmentKey._valuesEqual(42, 42) == true)
+        #expect(IntEnvironmentKey._valuesEqual(42, 43) == false)
+        
+        #expect(OptionalStringEnvironmentKey._valuesEqual(nil, nil) == true)
+        #expect(OptionalStringEnvironmentKey._valuesEqual("test", "test") == true)
+        #expect(OptionalStringEnvironmentKey._valuesEqual("test", nil) == false)
+        #expect(OptionalStringEnvironmentKey._valuesEqual(nil, "test") == false)
+    }
+
+    #if canImport(Darwin) // FIXME: compareValues is not implemented on OG yet
+    @Test
+    func nonEquatableValuesComparison() {
+        let struct1 = CustomStructEnvironmentKey.CustomStruct(value: 100)
+        let struct2 = CustomStructEnvironmentKey.CustomStruct(value: 100)
+        let struct3 = CustomStructEnvironmentKey.CustomStruct(value: 200)
+        
+        #expect(CustomStructEnvironmentKey._valuesEqual(struct1, struct2) == true)
+        #expect(CustomStructEnvironmentKey._valuesEqual(struct1, struct3) == false)
+    }
+    #endif
+
+    // MARK: - DerivedEnvironmentKey Tests
+    
+    @Test
+    func derivedEnvironmentKey() {
+        var environment = EnvironmentValues()
+        environment[StringEnvironmentKey.self] = "test value"
+        let derived = DerivedStringEnvironmentKey.value(in: environment)
+        #expect(derived == "d:test value")
+    }
+}