From 3b81985606de3a93d05febce62d55472415225c1 Mon Sep 17 00:00:00 2001
From: Zac Sweers <pandanomic@gmail.com>
Date: Sun, 25 Aug 2024 21:32:00 -0400
Subject: [PATCH] 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                  |  4 ++++
 .../foundation/DelicateCircuitFoundationApi.kt       | 12 ++++++++++++
 .../circuit/foundation/NavigableCircuitContent.kt    | 12 ++++++++++--
 .../circuit/retained/DelicateCircuitRetainedApi.kt   |  2 +-
 4 files changed, 27 insertions(+), 3 deletions(-)
 create mode 100644 circuit-foundation/src/commonMain/kotlin/com/slack/circuit/foundation/DelicateCircuitFoundationApi.kt

diff --git a/circuit-foundation/build.gradle.kts b/circuit-foundation/build.gradle.kts
index 1050b1f3f..3959131ee 100644
--- a/circuit-foundation/build.gradle.kts
+++ b/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 {
diff --git a/circuit-foundation/src/commonMain/kotlin/com/slack/circuit/foundation/DelicateCircuitFoundationApi.kt b/circuit-foundation/src/commonMain/kotlin/com/slack/circuit/foundation/DelicateCircuitFoundationApi.kt
new file mode 100644
index 000000000..a8b99daf7
--- /dev/null
+++ b/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
diff --git a/circuit-foundation/src/commonMain/kotlin/com/slack/circuit/foundation/NavigableCircuitContent.kt b/circuit-foundation/src/commonMain/kotlin/com/slack/circuit/foundation/NavigableCircuitContent.kt
index d6ef39c40..e81f05d7e 100644
--- a/circuit-foundation/src/commonMain/kotlin/com/slack/circuit/foundation/NavigableCircuitContent.kt
+++ b/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
+}
diff --git a/circuit-retained/src/commonMain/kotlin/com/slack/circuit/retained/DelicateCircuitRetainedApi.kt b/circuit-retained/src/commonMain/kotlin/com/slack/circuit/retained/DelicateCircuitRetainedApi.kt
index 92c440031..0e8837116 100644
--- a/circuit-retained/src/commonMain/kotlin/com/slack/circuit/retained/DelicateCircuitRetainedApi.kt
+++ b/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)