Update messaging for perception warning. (#96)

Author: mbrandonw

README.md

@@ -66,8 +66,10 @@ It's unfortunate to have to wrap your view's content in `WithPerceptionTracking`
 forget then you will helpfully get a runtime warning letting you know that observation is not
 set up correctly:
 
-> 🟣 Runtime Warning: Perceptible state was accessed but is not being tracked. Track changes to
-> state by wrapping your view in a 'WithPerceptionTracking' view.
+> 🟣 Runtime Warning: Perceptible state was accessed but is not being tracked. Track changes
+> to state by wrapping your view in a 'WithPerceptionTracking' view. This must also be done
+> for any escaping, trailing closures, such as 'GeometryReader', `LazyVStack` (and all lazy
+> views), navigation APIs ('sheet', 'popover', 'fullScreenCover', etc.), and others.
 
 ### Bindable
 

Sources/Perception/Internal/Locals.swift

@@ -1,10 +1,26 @@
 import Foundation
 
+/// Globally enable or disable perception checks.
+///
+/// The library performs certain runtime checks to make sure that the tools are being used
+/// correctly. In particular, view bodies must be wrapped in the ``WithPerceptionTracking`` view
+/// in order for observation to be properly tracked. If the library detects state is accessed
+/// without being inside ``WithPerceptionTracking``, a runtime warning is triggered to let you
+/// know there is something to fix.
+///
+/// This check only happens in `DEBUG` builds, and so does not affect App Store releases of your
+/// app. However, the checks can sometimes be costly and slow down your app in development. If
+/// you wish to fully disable the checks, you can set this boolean to `false.`
 public var isPerceptionCheckingEnabled: Bool {
   get { perceptionChecking.isPerceptionCheckingEnabled }
   set { perceptionChecking.isPerceptionCheckingEnabled = newValue }
 }
 
+public enum _PerceptionLocals {
+  @TaskLocal public static var isInPerceptionTracking = false
+  @TaskLocal public static var skipPerceptionChecking = false
+}
+
 private let perceptionChecking = PerceptionChecking()
 
 private class PerceptionChecking: @unchecked Sendable {

Sources/Perception/PerceptionChecking.swift

@@ -214,7 +214,9 @@ extension PerceptionRegistrar: Hashable {
         reportIssue(
           """
           Perceptible state was accessed but is not being tracked. Track changes to state by \
-          wrapping your view in a 'WithPerceptionTracking' view.
+          wrapping your view in a 'WithPerceptionTracking' view. This must also be done for any \
+          escaping, trailing closures, such as 'GeometryReader', `LazyVStack` (and all lazy \
+          views), navigation APIs ('sheet', 'popover', 'fullScreenCover', etc.), and others.
           """
         )
       }

Sources/Perception/PerceptionRegistrar.swift

@@ -30,11 +30,19 @@
   /// }
   /// ```
   ///
+  /// > Note: Other common escaping closures to be aware of:
+  /// > * Reader views, such as `GeometryReader`, ScrollViewReader`, etc.
+  /// > * Lazy views such as `LazyVStack`, `LazyVGrid`, etc.
+  /// > * Navigation APIs, such as `sheet`, `popover`, `fullScreenCover`, `navigationDestination`,
+  /// etc.
+  ///
   /// If a field of a `@Perceptible` model is accessed in a view while _not_ inside
   /// ``WithPerceptionTracking``, then a runtime warning will helpfully be triggered:
   ///
   /// > 🟣 Runtime Warning: Perceptible state was accessed but is not being tracked. Track changes
-  /// > to state by wrapping your view in a 'WithPerceptionTracking' view.
+  /// > to state by wrapping your view in a 'WithPerceptionTracking' view. This must also be done
+  /// > for any escaping, trailing closures, such as 'GeometryReader', `LazyVStack` (and all lazy
+  /// > views), navigation APIs ('sheet', 'popover', 'fullScreenCover', etc.), and others.
   ///
   /// To debug this, expand the warning in the Issue Navigator of Xcode (cmd+5), and click through
   /// the stack frames displayed to find the line in your view where you are accessing state without

Sources/Perception/WithPerceptionTracking.swift

@@ -613,7 +613,9 @@
     XCTExpectFailure(failingBlock: failingBlock) {
       $0.compactDescription == """
         failed - Perceptible state was accessed but is not being tracked. Track changes to state \
-        by wrapping your view in a 'WithPerceptionTracking' view.
+        by wrapping your view in a 'WithPerceptionTracking' view. This must also be done for any \
+        escaping, trailing closures, such as 'GeometryReader', `LazyVStack` (and all lazy \
+        views), navigation APIs ('sheet', 'popover', 'fullScreenCover', etc.), and others.
         """
     }
   }