Skip to content

Commit b1efe0b

Browse files
xxfastxxfast
committed
Update documentation with basic navigation usecases
1 parent b237ff9 commit b1efe0b

File tree

8 files changed

+159
-7
lines changed

8 files changed

+159
-7
lines changed

‎README.md‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -32,8 +32,8 @@ A detailed breakdown available in this [Medium article](https://proandroiddev.co
3232

3333
```kotlin
3434
// Declare your screen configurations for type-safety
35-
@Parcelize
36-
sealed class Screen: Parcelable {
35+
@Serializable
36+
sealed class Screen {
3737
object List : Screen()
3838
data class Details(val detail: String) : Screen()
3939
}

‎docs/cfg/buildprofiles.xml‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -9,6 +9,7 @@
99
<color-preset>soft</color-preset>
1010
<primary-color>blue</primary-color>
1111
<header-logo>decompose_router.svg</header-logo>
12+
<custom-favicons>fav.svg</custom-favicons>
1213
</variables>
1314
</build-profile>
1415

‎docs/decompose-router.tree‎

Lines changed: 5 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -7,7 +7,8 @@
77
start-page="overview.md">
88

99
<toc-element topic="overview.md"/>
10-
<toc-element topic="installation.md" toc-title="Installation">
11-
</toc-element>
12-
<toc-element topic="platform-configurations.md"/>
13-
</instance-profile>
10+
<toc-element topic="installation.md" toc-title="Installation"/><toc-element topic="platform-configurations.md"/>
11+
<toc-element toc-title="Using Decompose Router" topic="using-decompose-router.md">
12+
<toc-element topic="using-stack-navigation.md"/>
13+
</toc-element><toc-element topic="Scoping-Instances-to-Screens.md"/>
14+
</instance-profile>

‎docs/images/fav.svg‎

Lines changed: 7 additions & 0 deletions
Loading

‎docs/topics/Scoping-Instances-to-Screens.md‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,3 @@
1+
# Scoping Instances to Screens
2+
3+
TODO 🚧

‎docs/topics/overview.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
1-
# Decompose Router
1+
# Overview
22

33
<img src="decompose_router.svg" alt="Alt text" width="200"/>
44

‎docs/topics/using-decompose-router.md‎

Lines changed: 42 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,42 @@
1+
# How to Use Decompose Router
2+
3+
Decompose router supports the following navigation models, that is driven by a [model](#model-driven-navigation)
4+
5+
1. [Stack navigation](using-stack-navigation.md)
6+
2. Page navigation 🚧
7+
3. Slot navigation 🚧
8+
9+
These are the same ones supported by [Decompose](https://github.com/arkivanov/Decompose)
10+
11+
<deflist type="narrow" sorted="desc">
12+
<def title="Stack navigation">
13+
Stack is a navigation model for managing a stack of components
14+
</def>
15+
<def title="Page navigation">
16+
Pages is a navigation model for managing a list of components (pages) with one selected (active) component.
17+
</def>
18+
<def title="Slot navigation">
19+
Slot is a navigation model that allows only one child component at a time, or none.
20+
</def>
21+
</deflist>
22+
23+
## Model driven navigation
24+
25+
Model driven navigation is the idea that each node of your navigation hierarchy is represented by a model with a strict schema (as opposed to a URL string).
26+
This strict schema makes all the navigation arguments type-safe
27+
28+
For example, a typical list/detail screen flow would look like this
29+
```kotlin
30+
@Serializable
31+
sealed class Screens {
32+
@Serializable data object List: Screens()
33+
@Serializable data class Details(val number: Int): Screens()
34+
}
35+
```
36+
37+
> `@Serializable` is optional but **preferred** if you want your screen state to
38+
> 1. Be retained across configuration changes (on Android)
39+
> 2. Survive process death (on Android)
40+
>
41+
> If these are not a concern for the given screens - you may omit `@Serialisable` from the given screen.
42+

‎docs/topics/using-stack-navigation.md‎

Lines changed: 98 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,98 @@
1+
# Stack Navigation
2+
3+
Define your navigation model, (as already covered
4+
in [model-driven navigation section](using-decompose-router.md#model-driven-navigation))
5+
6+
```kotlin
7+
@Serializable
8+
sealed class Screens {
9+
@Serializable
10+
data object List : Screens()
11+
@Serializable
12+
data class Details(val number: Int) : Screens()
13+
}
14+
```
15+
16+
## Creating a router with stack navigation model
17+
18+
````kotlin
19+
@Composable
20+
fun HomeScreen() {
21+
val router: Router<Screens> = rememberRouter(Screens::class) {
22+
listOf(Screens.List) // Root screen to be set here
23+
}
24+
}
25+
````
26+
27+
> Due to this [issue](https://github.com/JetBrains/compose-multiplatform/issues/2900), you will still need to provide this
28+
> type `Screen:class` manually for now.
29+
> Once resolved, you will be able to use the `inline` `refied` (and nicer) signature
30+
> ```kotlin
31+
> val router: Router<Screens> = rememberRouter { listOf(Screens.List) }
32+
> ```
33+
{style="warning"}
34+
35+
## Consuming the state from the router
36+
37+
Use `RoutedContent` to consume the state from the router.
38+
39+
```kotlin
40+
@Composable
41+
fun HomeScreen() {
42+
val router: Router<Screens> = rememberRouter(Screens::class) { listOf(Screens.List) }
43+
44+
RoutedContent(router = router) { screen: Screens ->
45+
when (screen) {
46+
HomeScreens.List -> ListScreen()
47+
is Details -> DetailScreen(screen.number)
48+
}
49+
}
50+
}
51+
```
52+
53+
## Navigating with stack navigation router
54+
55+
Decompose-router exposes the same Decompose stack navigator extension [functions](https://arkivanov.github.io/Decompose/navigation/stack/navigation/#stacknavigator-extension-functions)
56+
57+
58+
```kotlin
59+
val router: Router<HomeScreens> = rememberRouter(HomeScreens::class) { listOf(HomeScreens.List) }
60+
61+
// To go to details screen
62+
Button(onClick = { number -> router.push(Details(number)) })
63+
64+
// To go back to list screen
65+
Button(onClick = { router.pop() })
66+
```
67+
68+
## Animating screen transitions
69+
70+
Decompose-router simply exposes Decompose [API]( https://arkivanov.github.io/Decompose/extensions/compose/#animations)
71+
```kotlin
72+
RoutedContent(
73+
router = router,
74+
animation = predictiveBackAnimation(
75+
animation = stackAnimation(slide()),
76+
),
77+
)
78+
```
79+
80+
### For predictive back animations
81+
Decompose-router simply exposes Decompose [API]( https://arkivanov.github.io/Decompose/extensions/compose/#predictive-back-gesture)
82+
83+
```kotlin
84+
RoutedContent(
85+
router = router,
86+
animation = predictiveBackAnimation(
87+
animation = stackAnimation(slide()),
88+
onBack = { router.pop() },
89+
backHandler = LocalRouterContext.current.backHandler
90+
)
91+
)
92+
```
93+
94+
<seealso style="cards">
95+
<category ref="external">
96+
<a href="https://arkivanov.github.io/Decompose">Decompose API Documentation</a>
97+
</category>
98+
</seealso>

0 commit comments

Comments
 (0)