Promote LocalBackStack to public API (#1601)

We've seen some use cases in testing and interop to swift that warrant
making this public but delicate.

Intentionally omitting this from the changelog as it's not something we
want to advertise much.

circuit-foundation/build.gradle.kts

@@ -1,5 +1,6 @@
 // Copyright (C) 2022 Slack Technologies, LLC
 // SPDX-License-Identifier: Apache-2.0
+import org.jetbrains.kotlin.gradle.ExperimentalKotlinGradlePluginApi
 import org.jetbrains.kotlin.gradle.targets.js.dsl.ExperimentalWasmDsl
 import org.jetbrains.kotlin.gradle.tasks.KotlinCompile
 
@@ -43,6 +44,9 @@ kotlin {
 
   applyDefaultHierarchyTemplate()
 
+  @OptIn(ExperimentalKotlinGradlePluginApi::class)
+  compilerOptions.optIn.add("com.slack.circuit.foundation.DelicateCircuitFoundationApi")
+
   sourceSets {
     commonMain {
       dependencies {

circuit-foundation/src/commonMain/kotlin/com/slack/circuit/foundation/DelicateCircuitFoundationApi.kt

@@ -0,0 +1,12 @@
+// Copyright (C) 2024 Slack Technologies, LLC
+// SPDX-License-Identifier: Apache-2.0
+package com.slack.circuit.foundation
+
+import kotlin.annotation.AnnotationTarget.FUNCTION
+import kotlin.annotation.AnnotationTarget.PROPERTY
+
+/** Indicates that the annotated foundation API is delicate and should be used carefully. */
+@RequiresOptIn
+@Retention(AnnotationRetention.BINARY)
+@Target(FUNCTION, PROPERTY)
+public annotation class DelicateCircuitFoundationApi

circuit-foundation/src/commonMain/kotlin/com/slack/circuit/foundation/NavigableCircuitContent.kt

@@ -20,6 +20,7 @@ import androidx.compose.animation.togetherWith
 import androidx.compose.runtime.Composable
 import androidx.compose.runtime.CompositionLocalProvider
 import androidx.compose.runtime.Immutable
+import androidx.compose.runtime.ProvidableCompositionLocal
 import androidx.compose.runtime.compositionLocalOf
 import androidx.compose.runtime.currentCompositeKeyHash
 import androidx.compose.runtime.getValue
@@ -354,7 +355,14 @@ public object NavigatorDefaults {
 }
 
 /**
- * Internal API to access the [BackStack] from within a [CircuitContent] or
+ * Delicate API to access the [BackStack] from within a [CircuitContent] or
  * [rememberAnsweringNavigator] composable, useful for cases where we create nested nav handling.
+ *
+ * This is generally considered an internal API to Circuit, but can be useful for interop cases and
+ * testing of [rememberAnsweringNavigator] APIs. As such, it's public but annotated as
+ * [DelicateCircuitFoundationApi].
  */
-internal val LocalBackStack = compositionLocalOf<BackStack<out Record>?> { null }
+@DelicateCircuitFoundationApi
+public val LocalBackStack: ProvidableCompositionLocal<BackStack<out Record>?> = compositionLocalOf {
+  null
+}

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

@@ -4,7 +4,7 @@ package com.slack.circuit.retained
 
 import kotlin.annotation.AnnotationTarget.FUNCTION
 
-/** Indicates that the annotated API is delicate and should be used carefully. */
+/** Indicates that the annotated retained API is delicate and should be used carefully. */
 @RequiresOptIn
 @Retention(AnnotationRetention.BINARY)
 @Target(FUNCTION)