Make circuit-retained fully optional (#354)

Followup to #352 and related to #349, this makes `circuit-retained` a
fully optional artifact and documents its setup and installation. A few
opportunistic improvements are made as well around idiomatic composition
local setup and some repo infra stuff

Author: ZacSweers

.github/workflows/mkdocs-requirements.txt

@@ -3,7 +3,7 @@ future==0.18.2
 Jinja2==3.1.2
 livereload==2.6.3
 lunr==0.6.2
-Markdown==3.4.1
+Markdown==3.3.7
 MarkupSafe==2.1.1
 mkdocs==1.4.2
 mkdocs-macros-plugin==0.7.0

.gitignore

@@ -23,6 +23,7 @@ out/
 
 docs/code-of-conduct.md
 docs/contributing.md
+docs/changelog.md
 docs/api/
 site/
 temp-clone/

circuit-retained/README.md

@@ -1,7 +1,22 @@
 circuit-retained
 ================
 
-This artifact contains an implementation of `rememberRetained` and `produceRetainedState`. This is
+This optional artifact contains an implementation of `rememberRetained` and `produceRetainedState`. This is
 useful for cases where you want to retain non-parcelable state across configuration changes. This
 comes at the cost of not participating in the `SavedStateRegistry` and thus not being able to
 persist across process death.
+
+The only meaningful implementation in this artifact is for Android, where a backing `ViewModel` is used
+to hold values. If you're not running this on Android, you shouldn't need this artifact.
+
+## Installation
+
+Simply provide the `LocalRetainedStateRegistry` composition local using `continuityRetainedStateRegistry()`.
+
+```kotlin
+CompositionLocalProvider(
+  LocalRetainedStateRegistry provides continuityRetainedStateRegistry(),
+) {
+  // Content
+}
+```

circuit-retained/android-tests/src/androidTest/kotlin/com/circuit/retained/android/RetainedTest.kt

@@ -30,7 +30,7 @@ import androidx.lifecycle.ViewModelProvider
 import androidx.test.core.app.ActivityScenario
 import com.google.common.truth.Truth.assertThat
 import com.slack.circuit.retained.Continuity
-import com.slack.circuit.retained.LocalRetainedStateRegistryOwner
+import com.slack.circuit.retained.LocalRetainedStateRegistry
 import com.slack.circuit.retained.continuityRetainedStateRegistry
 import com.slack.circuit.retained.rememberRetained
 import leakcanary.DetectLeaksAfterTestSuccess.Companion.detectLeaksAfterTestSuccessWrapping
@@ -239,7 +239,7 @@ class RetainedTest {
     scenario.onActivity { activity ->
       activity.setContent {
         CompositionLocalProvider(
-          LocalRetainedStateRegistryOwner provides continuityRetainedStateRegistry(vmFactory),
+          LocalRetainedStateRegistry provides continuityRetainedStateRegistry(vmFactory),
         ) {
           content()
         }

circuit-retained/src/commonMain/kotlin/com/slack/circuit/retained/RememberRetained.kt

@@ -67,7 +67,7 @@ import androidx.compose.runtime.rememberUpdatedState
  */
 @Composable
 public fun <T : Any> rememberRetained(vararg inputs: Any?, key: String? = null, init: () -> T): T {
-  val registry = LocalRetainedStateRegistryOwner.current
+  val registry = LocalRetainedStateRegistry.current
   // Short-circuit no-ops
   if (registry === NoOpRetainedStateRegistry) {
     return when (inputs.size) {

circuit-retained/src/commonMain/kotlin/com/slack/circuit/retained/RetainedStateRegistry.kt

@@ -2,9 +2,7 @@
 // SPDX-License-Identifier: Apache-2.0
 package com.slack.circuit.retained
 
-import androidx.compose.runtime.Composable
-import androidx.compose.runtime.CompositionLocalProvider
-import androidx.compose.runtime.ProvidedValue
+import androidx.compose.runtime.ProvidableCompositionLocal
 import androidx.compose.runtime.staticCompositionLocalOf
 import com.slack.circuit.retained.RetainedStateRegistry.Entry
 
@@ -69,25 +67,10 @@ public fun RetainedStateRegistry(values: Map<String, List<Any?>>?): RetainedStat
   )
 
 /** CompositionLocal with a current [RetainedStateRegistry] instance. */
-public object LocalRetainedStateRegistryOwner {
-  private val LocalRetainedStateRegistry =
-    staticCompositionLocalOf<RetainedStateRegistry> { NoOpRetainedStateRegistry }
-
-  /**
-   * Returns current composition local value for the owner or errors if one has not been provided.
-   */
-  public val current: RetainedStateRegistry
-    @Composable get() = LocalRetainedStateRegistry.current
-
-  /**
-   * Associates a [LocalRetainedStateRegistry] key to a value in a call to
-   * [CompositionLocalProvider].
-   */
-  @Composable
-  public infix fun provides(registry: RetainedStateRegistry): ProvidedValue<RetainedStateRegistry> {
-    return LocalRetainedStateRegistry.provides(registry)
+public val LocalRetainedStateRegistry: ProvidableCompositionLocal<RetainedStateRegistry> =
+  staticCompositionLocalOf {
+    NoOpRetainedStateRegistry
   }
-}
 
 internal class RetainedStateRegistryImpl(retained: MutableMap<String, List<Any?>>?) :
   MutableRetainedStateRegistry {

circuit/build.gradle.kts

@@ -20,7 +20,6 @@ kotlin {
         api(libs.compose.runtime)
         api(libs.coroutines)
         api(projects.backstack)
-        api(projects.circuitRetained)
       }
     }
     maybeCreate("androidMain").apply {

circuit/src/androidMain/kotlin/com/slack/circuit/CircuitCompositionLocals.android.kt

@@ -9,8 +9,6 @@ import androidx.compose.runtime.ProvidedValue
 import androidx.compose.runtime.compositionLocalOf
 import androidx.compose.runtime.staticCompositionLocalOf
 
-@Composable internal expect fun PlatformCompositionLocals(content: @Composable () -> Unit)
-
 /**
  * Provides the given [circuitConfig] as a [CompositionLocal] to all composables within [content].
  * Also adds any other composition locals that Circuit needs.
@@ -20,7 +18,7 @@ public fun CircuitCompositionLocals(circuitConfig: CircuitConfig, content: @Comp
   CompositionLocalProvider(
     LocalCircuitOwner provides circuitConfig,
   ) {
-    PlatformCompositionLocals(content)
+    content()
   }
 }