Added some scoped remember compose navigator functions

navigation-compose/src/commonMain/kotlin/com.chrynan.navigation.compose/RememberComposeNavigatorUtils.kt

@@ -14,7 +14,7 @@ import com.chrynan.navigation.Navigator
  * [ComposeNavigatorByContent].
  *
  * Example usage:
- * ```
+ * ```kotlin
  * val navigator = rememberNavigatorByContent("Greeting") { Text("Hello") }
  *
  * // The NavContainer will start by displaying the initial content, which in this case is "Hello".
@@ -48,7 +48,7 @@ fun <T> rememberNavigatorByContent(
  * [ComposeNavigatorByKey.goTo] function.
  *
  * Example usage:
- * ```
+ * ```kotlin
  * val navigator = rememberNavigatorByKey("Greeting") { key ->
  * when(key) {
  * "Greeting" -> Text("Hello")
@@ -69,6 +69,11 @@ fun <T> rememberNavigatorByContent(
  *
  * **Note:** That it is typical to use a [ComposeNavigator] with a [NavContainer] to display the [Composable] content
  * and listen to changes.
+ *
+ * **Note:** This function differs slightly from the [rememberNavigatorByKey] function in that it only uses a single
+ * scope of type [Nothing]. This means that scopes cannot be changed on the returned [ComposeNavigatorByKeyViewModel].
+ *
+ * @see [rememberNavigatorByKey]
  */
 @ExperimentalNavigationApi
 @Composable
@@ -83,14 +88,74 @@ fun <Key> rememberNavigatorByKey(
  )
 }
 
+/**
+ * Creates and remembers a [ComposeNavigator] that can navigate with a key. This allows for specifying the [Composable]
+ * content up front when creating this [ComposeNavigatorByKey] and simply navigating with a key from the
+ * [ComposeNavigatorByKey.goTo] function.
+ *
+ * Example usage:
+ * ```kotlin
+ * val navigator = rememberNavigatorByKey(
+ * initialScope = BottomNavBarItem.HELLO,
+ * initialKeys = { scope ->
+ * when(scope) {
+ * BottomNavBarItem.HELLO -> "Greeting"
+ * BottomNavBarItem.GOODBYE -> "Farewell"
+ * ...
+ * }
+ * },
+ * content = { key ->
+ * when(key) {
+ * "Greeting" -> Text("Hello")
+ * "Farewell" -> Text("Good-bye")
+ * else -> Text("Unexpected Key: $key")
+ * }
+ * }
+ * )
+ *
+ * // The NavContainer will start by displaying the initial content, which in this case is "Hello"
+ * NavContainer(navigator)
+ *
+ * // The above NavContainer will display "Good Bye" after the following call:
+ * navigator.goTo("Farewell")
+ *
+ * // Goes back to the initial content: "Hello":
+ * navigator.goBack()
+ *
+ * // Changes the scope to BottomNavBarItem.GOODBYE and displays its initial key, which in this case is "Farewell"
+ * navigator.changeScope(BottomNavBarItem.GOODBYE)
+ * ```
+ *
+ * **Note:** That it is typical to use a [ComposeNavigator] with a [NavContainer] to display the [Composable] content
+ * and listen to changes.
+ *
+ * **Note:** That this function differs slightly from the [rememberNavigatorByKey] function in that this function allows
+ * changing of scopes, which is useful for more complex navigation.
+ *
+ * @see [rememberNavigatorByKey]
+ */
+@ExperimentalNavigationApi
+@Composable
+fun <Scope, Key> rememberNavigatorByKey(
+ initialScope: Scope,
+ initialKeys: (Scope) -> Key,
+ content: @Composable ComposeNavigationKeyScope<Key>.(key: Key) -> Unit
+): ComposeNavigatorByKeyViewModel<Scope, Key> = remember {
+ ComposeNavigatorByKeyViewModel(
+ initialScope = initialScope,
+ initialKeys = initialKeys,
+ content = content
+ )
+}
+
 /**
  * Creates and remembers a [ComposeNavigator] that can navigate with a [NavigationIntent] as a key. This allows for
  * specifying the [Composable] content up front when creating this [ComposeNavigatorByKey] and simply navigating with
  * a [NavigationIntent] key from the [ComposeNavigatorByKey.goTo] function. The returned [ComposeNavigator] implements
  * the [Navigator] interface.
  *
  * Example usage:
- * ```
+ * ```kotlin
  * val navigator = rememberNavigatorByKey(HomeNavigationIntent.Greeting) { navigationIntent ->
  * when(navigationIntent) {
  * HomeNavigationIntent.Greeting -> Text("Hello")
@@ -110,6 +175,12 @@ fun <Key> rememberNavigatorByKey(
  *
  * **Note:** That it is typical to use a [ComposeNavigator] with a [NavContainer] to display the [Composable] content
  * and listen to changes.
+ *
+ * **Note:** This function differs slightly from the [rememberNavigatorByIntent] function in that it only uses a single
+ * scope of type [Nothing]. This means that scopes cannot be changed on the returned
+ * [ComposeNavigationIntentNavigatorByKeyViewModel].
+ *
+ * @see [rememberNavigatorByIntent]
  */
 @ExperimentalNavigationApi
 @Composable
@@ -123,3 +194,60 @@ fun <Intent : NavigationIntent> rememberNavigatorByIntent(
  content = content
  )
 }
+
+/**
+ * Creates and remembers a [ComposeNavigator] that can navigate with a [NavigationIntent] as a key. This allows for
+ * specifying the [Composable] content up front when creating this [ComposeNavigatorByKey] and simply navigating with
+ * a [NavigationIntent] key from the [ComposeNavigatorByKey.goTo] function. The returned [ComposeNavigator] implements
+ * the [Navigator] interface.
+ *
+ * Example usage:
+ * ```kotlin
+ * val navigator = rememberNavigatorByKey(
+ * initialScope = BottomNavBarItem.HELLO,
+ * initialKeys = { scope ->
+ * when(scope) {
+ * BottomNavBarItem.HELLO -> HomeNavigationIntent.Greeting
+ * BottomNavBarItem.GOODBYE -> HomeNavigationIntent.Farewell
+ * ...
+ * }
+ * },
+ * content = { navigationIntent ->
+ * when(navigationIntent) {
+ * HomeNavigationIntent.Greeting -> Text("Hello")
+ * HomeNavigationIntent.Farewell -> Text("Good-bye")
+ * }
+ * }
+ * )
+ *
+ * // The NavContainer will start by displaying the initial content, which in this case is "Hello"
+ * NavContainer(navigator)
+ *
+ * // The above NavContainer will display "Good Bye" after the following call:
+ * navigator.goTo(HomeNavigationIntent.Farewell)
+ *
+ * // Goes back to the initial content: "Hello":
+ * navigator.goBack()
+ * ```
+ *
+ * **Note:** That it is typical to use a [ComposeNavigator] with a [NavContainer] to display the [Composable] content
+ * and listen to changes.
+ *
+ * **Note:** That this function differs slightly from the [rememberNavigatorByIntent] function in that this function
+ * allows changing of scopes, which is useful for more complex navigation.
+ *
+ * @see [rememberNavigatorByIntent]
+ */
+@ExperimentalNavigationApi
+@Composable
+fun <Scope, Intent : NavigationIntent> rememberNavigatorByIntent(
+ initialScope: Scope,
+ initialIntents: (Scope) -> Intent,
+ content: @Composable ComposeNavigationIntentScope<Intent>.(intent: Intent) -> Unit
+): ComposeNavigationIntentNavigatorByKeyViewModel<Scope, Intent> = remember {
+ ComposeNavigationIntentNavigatorByKeyViewModel(
+ initialScope = initialScope,
+ initialKeys = initialIntents,
+ content = content
+ )
+}