Merge remote-tracking branch 'origin/main' into fix-sharing-docs

Author: mbrandonw

Examples/SyncUps/SyncUps/Dependencies/SpeechRecognizer.swift

@@ -33,14 +33,12 @@ extension SpeechClient: DependencyKey {
   }
 
   static var previewValue: SpeechClient {
-    let isRecording = LockIsolated(false)
-    return Self(
+    Self(
       authorizationStatus: { .authorized },
       requestAuthorization: { .authorized },
       startTask: { _ in
         AsyncThrowingStream { continuation in
           Task { @MainActor in
-            isRecording.setValue(true)
             var finalText = """
               Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor \
               incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud \
@@ -50,7 +48,7 @@ extension SpeechClient: DependencyKey {
               officia deserunt mollit anim id est laborum.
               """
             var text = ""
-            while isRecording.value {
+            while !finalText.isEmpty {
               let word = finalText.prefix { $0 != " " }
               try await Task.sleep(for: .milliseconds(word.count * 50 + .random(in: 0...200)))
               finalText.removeFirst(word.count)

Sources/ComposableArchitecture/Documentation.docc/Articles/FAQ.md

@@ -217,7 +217,7 @@ However, one does not need to have any prior experience with these concepts. The
 [dependency-management-article]: <doc:DependencyManagement>
 [sharing-state-article]: <doc:SharingState>
 [navigation-article]: <doc:Navigation>
-[testing-article]: <doc:Testing>
+[testing-article]: <doc:TestingTCA>
 [migration-1.7-article]: <doc:MigratingTo1.7>
 [migration-1.10-article]: <doc:MigratingTo1.10>
 [sync-ups-tutorial]: <doc:BuildingSyncUps>

Sources/ComposableArchitecture/Documentation.docc/Articles/GettingStarted.md

@@ -252,7 +252,7 @@ doing much additional work.
 
 ## Testing your feature
 
-> Note: For more in-depth information on testing, see the dedicated <doc:Testing> 
+> Note: For more in-depth information on testing, see the dedicated <doc:TestingTCA> 
 article.
 
 To test use a `TestStore`, which can be created with the same information as the `Store`, but it 
@@ -464,7 +464,7 @@ let store = TestStore(initialState: Feature.State()) {
 
 That is the basics of building and testing a feature in the Composable Architecture. There are 
 _a lot_ more things to be explored. Be sure to check out the <doc:MeetComposableArchitecture> 
-tutorial, as well as dedicated articles on <doc:DependencyManagement>, <doc:Testing>, 
+tutorial, as well as dedicated articles on <doc:DependencyManagement>, <doc:TestingTCA>, 
 <doc:Navigation>, <doc:Performance>, and more. Also, the [Examples][examples] directory has 
 a bunch of projects to explore to see more advanced usages.
 

Sources/ComposableArchitecture/Documentation.docc/Articles/SharingState.md

@@ -485,7 +485,7 @@ Shared state behaves quite a bit different from the regular state held in Compos
 features. It is capable of being changed by any part of the application, not just when an action is
 sent to the store, and it has reference semantics rather than value semantics. Typically references
 cause serious problems with testing, especially exhaustive testing that the library prefers (see
-<doc:Testing>), because references cannot be copied and so one cannot inspect the changes 
+<doc:TestingTCA>), because references cannot be copied and so one cannot inspect the changes 
 before and after an action is sent.
 
 For this reason, the `@Shared` property wrapper does extra work during testing to preserve a 
@@ -691,11 +691,11 @@ func basics() {
 However, if your test suite is a part of an app target, then the entry point of the app will execute
 and potentially cause an early access of `@Shared`, thus capturing a different default value than
 what is specified above. This quirk of tests in app targets is documented in
-<doc:Testing#Testing-gotchas> of the <doc:Testing> article, and a similar quirk
+<doc:TestingTCA#Testing-gotchas> of the <doc:TestingTCA> article, and a similar quirk
 exists for Xcode previews and is discussed below in <doc:SharingState#Gotchas-of-Shared>.
 
 The most robust workaround to this issue is to simply not execute your app's entry point when tests
-are running, which we detail in <doc:Testing#Testing-host-application>. This makes it so that you
+are running, which we detail in <doc:TestingTCA#Testing-host-application>. This makes it so that you
 are not accidentally execute network requests, tracking analytics, etc. while running tests.
 
 You can also work around this issue by simply setting the shared state again after initializing
@@ -1050,3 +1050,62 @@ extension AppState: Codable {
   }
 }
 ```
+
+#### Previews
+
+When a preview is run in an app target, the entry point is also created. This means if your entry
+point looks something like this:
+
+```swift
+@main
+struct MainApp: App {
+  let store = Store(…)
+
+  var body: some Scene {
+    …
+  }
+}
+```
+
+…then a store will be created each time you run your preview. This can be problematic with `@Shared`
+and persistence strategies because the first access of a `@Shared` property will use the default
+value provided, and that will cause `@Shared`'s created later to ignore the default. That will mean
+you cannot override shared state in previews.
+
+The fix is to delay creation of the store until the entry point's `body` is executed. Further, it
+can be a good idea to also not run the `body` when in tests because that can also interfere with
+tests (as documented in <doc:TestingTCA#Testing-gotchas>). Here is one way this can be accomplished:
+
+```swift
+import ComposableArchitecture
+import SwiftUI
+
+@main
+struct MainApp: App {
+  @MainActor
+  static let store = Store(…)
+
+  var body: some Scene {
+    WindowGroup {
+      if isTesting {
+        // NB: Don't run application in tests to avoid interference 
+        //     between the app and the test.
+        EmptyView()
+      } else {
+        AppView(store: Self.store)
+      }
+    }
+  }
+}
+```
+
+Alternatively you can take an extra step to override shared state in your previews:
+
+```swift
+#Preview {
+  @Shared(.appStorage("isOn")) var isOn = true
+  isOn = true
+}
+```
+
+The second assignment of `isOn` will guarantee that it holds a value of `true`.

Sources/ComposableArchitecture/Documentation.docc/Articles/StackBasedNavigation.md

@@ -350,7 +350,7 @@ with the parent.
 ## Testing
 
 A huge benefit of using the tools of this library to model navigation stacks is that testing becomes 
-quite easy. Further, using "non-exhaustive testing" (see <doc:Testing#Non-exhaustive-testing>) can 
+quite easy. Further, using "non-exhaustive testing" (see <doc:TestingTCA#Non-exhaustive-testing>) can 
 be very useful for testing navigation since you often only want to assert on a few high level 
 details and not all state mutations and effects.
 
@@ -537,11 +537,11 @@ other in a navigation stack.
 However, the more complex the features become, the more cumbersome testing their integration can be.
 By default, ``TestStore`` requires us to be exhaustive in our assertions. We must assert on how
 every piece of state changes, how every effect feeds data back into the system, and we must make
-sure that all effects finish by the end of the test (see <doc:Testing> for more info).
+sure that all effects finish by the end of the test (see <doc:TestingTCA> for more info).
 
 But ``TestStore`` also supports a form of testing known as "non-exhaustive testing" that allows you
 to assert on only the parts of the features that you actually care about (see 
-<doc:Testing#Non-exhaustive-testing> for more info).
+<doc:TestingTCA#Non-exhaustive-testing> for more info).
 
 For example, if we turn off exhaustivity on the test store (see ``TestStore/exhaustivity``) then we
 can assert at a high level that when the increment button is tapped twice that eventually we receive

Sources/ComposableArchitecture/Documentation.docc/Articles/Testing.md renamed to Sources/ComposableArchitecture/Documentation.docc/Articles/TestingTCA.md

@@ -512,7 +512,7 @@ the child domain without explicitly communicating with the parent.
 ## Testing
 
 A huge benefit of properly modeling your domains for navigation is that testing becomes quite easy.
-Further, using "non-exhaustive testing" (see <doc:Testing#Non-exhaustive-testing>) can be very 
+Further, using "non-exhaustive testing" (see <doc:TestingTCA#Non-exhaustive-testing>) can be very 
 useful for testing navigation since you often only want to assert on a few high level details and 
 not all state mutations and effects.
 
@@ -626,11 +626,11 @@ other.
 However, the more complex the features become, the more cumbersome testing their integration can be.
 By default, ``TestStore`` requires us to be exhaustive in our assertions. We must assert on how
 every piece of state changes, how every effect feeds data back into the system, and we must make
-sure that all effects finish by the end of the test (see <doc:Testing> for more info).
+sure that all effects finish by the end of the test (see <doc:TestingTCA> for more info).
 
 But ``TestStore`` also supports a form of testing known as "non-exhaustive testing" that allows you
 to assert on only the parts of the features that you actually care about (see 
-<doc:Testing#Non-exhaustive-testing> for more info).
+<doc:TestingTCA#Non-exhaustive-testing> for more info).
 
 For example, if we turn off exhaustivity on the test store (see ``TestStore/exhaustivity``) then we
 can assert at a high level that when the increment button is tapped twice that eventually we receive

Sources/ComposableArchitecture/Documentation.docc/Articles/TreeBasedNavigation.md

@@ -49,7 +49,7 @@ day-to-day when building applications, such as:
 
 - <doc:GettingStarted>
 - <doc:DependencyManagement>
-- <doc:Testing>
+- <doc:TestingTCA>
 - <doc:Navigation>
 - <doc:SharingState>
 - <doc:Performance>
@@ -70,7 +70,7 @@ day-to-day when building applications, such as:
 ### Testing
 
 - ``TestStore``
-- <doc:Testing>
+- <doc:TestingTCA>
 
 ### Integrations
 

Sources/ComposableArchitecture/Documentation.docc/ComposableArchitecture.md

@@ -15,4 +15,4 @@ instead.
 
 ### UIKit integration
 
-- ``ifLet(then:else:)``
+- ``Store/ifLet(then:else:)``

Sources/ComposableArchitecture/Documentation.docc/Extensions/Deprecations/StoreDeprecations.md

@@ -14,7 +14,7 @@
 
 - ``cancellable(id:cancelInFlight:)``
 - ``cancel(id:)``
-- ``withTaskCancellation(id:cancelInFlight:operation:)``
+- ``ComposableArchitecture/withTaskCancellation(id:cancelInFlight:isolation:operation:)``
 - ``_Concurrency/Task/cancel(id:)``
 
 ### Composition