PreCompose

https://tlaster.github.io/PreCompose/
Admin
PreCompose is a Kotlin Multiplatform library providing composable navigation and state management...
Tokens:5,012
Snippets:65
Trust Score:9.7
Update:5 months ago
Show doc for...
Tokens:
Raw
### Basic NavHost Setup

Source: https://tlaster.github.io/PreCompose/component/navigation.html

Defines a NavHost with a navigator and an initial route. Use this to set up the main navigation structure for your application.

```kotlin
val navigator = rememberNavigator()
NavHost(
    navigator = navigator,
    navTransition = NavTransition(),
    initialRoute = "/home",
) {
    scene(
        route = "/home",
        navTransition = NavTransition(),
    ) {
        Text(text = "Hello!")
    }
}
```

--------------------------------

### Greetings App with ViewModel using PreCompose

Source: https://tlaster.github.io/PreCompose/sample.html

Demonstrates navigation and ViewModel integration in a Jetpack Compose application using PreCompose. Requires PreComposeApp setup.

```kotlin
@Composable
fun App() {
    PreComposeApp {
        val navigator = rememberNavigator()
        MaterialTheme {
            NavHost(
                navigator = navigator,
                initialRoute = "/home"
            ) {
                scene(route = "/home") {
                    val homeViewModel = viewModel {
                        HomeViewModel()
                    }
                    val name by homeViewModel.name.observeAsState()
                    Column(
                        modifier = Modifier.fillMaxSize(),
                        horizontalAlignment = Alignment.CenterHorizontally,
                        verticalArrangement = Arrangement.Center
                    ) {
                        Text(
                            text = "Greet Me!",
                            style = MaterialTheme.typography.h6
                        )
                        Spacer(modifier = Modifier.height(30.dp))
                        TextField(
                            value = name,
                            maxLines = 1,
                            label = { Text(text = "Enter your name") },
                            onValueChange = {
                                homeViewModel.setName(it)
                            }
                        )
                        Spacer(modifier = Modifier.height(30.dp))
                        Button(
                            onClick = {
                                navigator.navigate(route = "/greeting/$name")
                            }
                        ) {
                            Text(text = "GO!")
                        }
                    }
                }
                scene(route = "/greeting/{name}") { backStackEntry ->
                    backStackEntry.path<String>("name")?.let { name ->
                        Column(
                            modifier = Modifier.fillMaxSize(),
                            horizontalAlignment = Alignment.CenterHorizontally,
                            verticalArrangement = Arrangement.Center
                        ) {
                            Text(
                                text = name,
                                style = MaterialTheme.typography.h6
                            )
                            Spacer(modifier = Modifier.height(30.dp))
                            Button(onClick = { navigator.goBack() }) {
                                Text(text = "GO BACK!")
                            }
                        }
                    }
                }
            }
        }
    }
}

class HomeViewModel : ViewModel() {
    val name = LiveData("")
    fun setName(value: String) {
        name.value = value
    }
}

```

--------------------------------

### NavHost Setup

Source: https://tlaster.github.io/PreCompose/component/navigation.html

Defines the navigation graph using NavHost, similar to Jetpack Navigation. It manages the back stack, lifecycle, and ViewModel for scenes.

```APIDOC
## NavHost Setup

### Description
Sets up the main navigation host for your application, defining the navigation graph and initial route.

### Usage
```kotlin
val navigator = rememberNavigator()
NavHost(
    navigator = navigator,
    navTransition = NavTransition(),
    initialRoute = "/home",
) {
    scene(
        route = "/home",
        navTransition = NavTransition(),
    ) {
        Text(text = "Hello!")
    }
}
```
```

--------------------------------

### Wrap App with PreComposeApp

Source: https://tlaster.github.io/PreCompose/setup.html

Wrap your root `@Composable` function `App()` with `PreComposeApp` to enable PreCompose's navigation and state management features.

```kotlin
@Composable
fun App() {
    PreComposeApp {
        // your app's content goes here
    }
}

```

--------------------------------

### Greetings App UI and Navigation with PreCompose

Source: https://tlaster.github.io/PreCompose/sample.html

This code defines the main Composable function for the Greetings App. It sets up the PreComposeApp, MaterialTheme, and NavHost for navigation between the home and greeting screens. The HomeViewModel is used to manage the input name state.

```kotlin
@Composable
fun App() {
    PreComposeApp {
        val navigator = rememberNavigator()
        MaterialTheme {
            NavHost(
                navigator = navigator,
                initialRoute = "/home"
            ) {
                scene(route = "/home") {
                    val homeViewModel = viewModel {
                        HomeViewModel()
                    }
                    val name by homeViewModel.name.collectAsStateWithLifecycle()
                    Column(
                        modifier = Modifier.fillMaxSize(),
                        horizontalAlignment = Alignment.CenterHorizontally,
                        verticalArrangement = Arrangement.Center
                    ) {
                        Text(
                            text = "Greet Me!",
                            style = MaterialTheme.typography.h6
                        )
                        Spacer(modifier = Modifier.height(30.dp))
                        TextField(
                            value = name,
                            maxLines = 1,
                            label = { Text(text = "Enter your name") },
                            onValueChange = homeViewModel::setName
                        )
                        Spacer(modifier = Modifier.height(30.dp))
                        Button(
                            onClick = {
                                navigator.navigate(route = "/greeting/$name")
                            }
                        ) {
                            Text(text = "GO!")
                        }
                    }
                }
                scene(route = "/greeting/{name}") { backStackEntry ->
                    backStackEntry.path<String>("name")?.let { name ->
                        Column(
                            modifier = Modifier.fillMaxSize(),
                            horizontalAlignment = Alignment.CenterHorizontally,
                            verticalArrangement = Arrangement.Center
                        ) {
                            Text(
                                text = name,
                                style = MaterialTheme.typography.h6
                            )
                            Spacer(modifier = Modifier.height(30.dp))
                            Button(onClick = navigator::goBack) {
                                Text(text = "GO BACK!")
                            }
                        }
                    }
                }
            }
        }
    }
}

class HomeViewModel : ViewModel() {
    val name = MutableStateFlow("")
    fun setName(value: String) {
        name.update { value }
    }
}

```

--------------------------------

### Navigate with NavOptions

Source: https://tlaster.github.io/PreCompose/component/navigation.html

Navigates to a route with specific navigation options, such as launching the scene as single top. Ensure the navigator is properly initialized.

```kotlin
navigator.navigate(
    "/home",
    NavOptions(
        launchSingleTop = true,
    ),
)
```

--------------------------------

### Navigate with PopUpTo

Source: https://tlaster.github.io/PreCompose/component/navigation.html

Navigates to a route and pops destinations from the back stack up to a specified route, optionally including that route. Useful for clearing the back stack.

```kotlin
navigator.navigate(
    "/detail",
    NavOptions(
        popUpTo = PopUpTo(
            route = "/home",
            inclusive = true,
        )
    ),
)
```

--------------------------------

### Define Static Scene Route

Source: https://tlaster.github.io/PreCompose/component/navigation.html

Defines a scene with a static route. This is the simplest way to define a navigation destination.

```kotlin
scene(route = "/home") {

}
```

--------------------------------

### CounterPresenter with Flow Action

Source: https://tlaster.github.io/PreCompose/component/molecule.html

Write a presenter that accepts a Flow of actions and returns a state. Use `collectAction` to process incoming actions.

```kotlin
@Composable
fun CounterPresenter(
    action: Flow<CounterAction>,
): CounterState {
    var count by remember { mutableStateOf(0) }

    action.collectAction {
        when (this) {
            CounterAction.Increment -> count++
            CounterAction.Decrement -> count--
        }
    }

    return CounterState("Clicked $count times")
}

```

--------------------------------

### Add PreCompose-Koin Dependency

Source: https://tlaster.github.io/PreCompose/component/koin.html

Add this dependency to your common module's commonMain source set to enable Koin integration with PreCompose.

```kotlin
api("moe.tlaster:precompose-koin:$precompose_version")
```

--------------------------------

### Add PreCompose Dependency

Source: https://tlaster.github.io/PreCompose/setup.html

Add this dependency to your common module's commonMain sourceSet. Remember to include compose.foundation and compose.animation. Optional dependencies for Molecule, ViewModel, and Koin integration are also listed.

```kotlin
api(compose.foundation)
api(compose.animation)
//...
api("moe.tlaster:precompose:$precompose_version")

// api("moe.tlaster:precompose-molecule:$precompose_version") // For Molecule intergration 

// api("moe.tlaster:precompose-viewmodel:$precompose_version") // For ViewModel intergration

// api("moe.tlaster:precompose-koin:$precompose_version") // For Koin intergration

```

--------------------------------

### CounterPresenter with State Action

Source: https://tlaster.github.io/PreCompose/component/molecule.html

An alternative presenter implementation that takes a lambda for handling actions directly.

```kotlin
@Composable
fun CounterPresenter(): CounterState {
    var count by remember { mutableStateOf(0) }
    return CounterState("Clicked $count times") {
        when (it) {
            CounterAction.Increment -> count++
            CounterAction.Decrement -> count--
        }
    }
}

```

--------------------------------

### NavOptions

Source: https://tlaster.github.io/PreCompose/component/navigation.html

Configuration options for navigation, including launch modes and pop-up behavior, similar to Jetpack Navigation's NavOptions.

```APIDOC
## NavOptions

### Description
Defines navigation behavior such as `launchSingleTop` and `popUpTo`.

### Usage
```kotlin
// Using launchSingleTop
navigator.navigate("/home", NavOptions(launchSingleTop = true))

// Using popUpTo
navigator.navigate("/detail", NavOptions(popUpTo = PopUpTo(route = "/home", inclusive = true)))
```
```

--------------------------------

### Add PreCompose ViewModel Dependency

Source: https://tlaster.github.io/PreCompose/component/view_model.html

Add this dependency to your common module's commonMain sourceSet to enable ViewModel functionality.

```kotlin
api("moe.tlaster:precompose-viewmodel:$precompose_version")
```

--------------------------------

### Navigation Transitions

Source: https://tlaster.github.io/PreCompose/component/navigation.html

Defines custom transitions for scene entry, exit, pause, and resume actions.

```APIDOC
## Navigation Transitions

### Description
Allows customization of visual transitions between scenes during navigation events.

### Transition Types
* `createTransition`: Transition for a scene appearing for the first time.
* `destroyTransition`: Transition for a scene disappearing permanently.
* `pauseTransition`: Transition for a scene being pushed onto the back stack.
* `resumeTransition`: Transition for a scene being brought back from the back stack.

### Usage
Transitions can be defined at the `NavHost` level or on individual `scene` definitions. Scene-specific transitions override `NavHost` transitions.

```kotlin
NavHost(
    navigator = navigator,
    navTransition = NavTransition(createTransition = ..., destroyTransition = ...),
    initialRoute = "/home",
) {
    scene(
        route = "/home",
        navTransition = NavTransition(pauseTransition = ..., resumeTransition = ...),
    ) {
        Text(text = "Hello!")
    }
}
```
```

--------------------------------

### Define a Basic ViewModel

Source: https://tlaster.github.io/PreCompose/component/view_model.html

Define your ViewModel by extending the ViewModel class. This is similar to how you would define a ViewModel in Jetpack Compose.

```kotlin
class HomeViewModel : ViewModel() {

}
```

--------------------------------

### Add PreCompose-Molecule Dependency

Source: https://tlaster.github.io/PreCompose/component/molecule.html

Add this dependency to your common module's commonMain sourceSet to integrate PreCompose with Molecule.

```kotlin
api("moe.tlaster:precompose-molecule:$precompose_version")

```

--------------------------------

### Query String Handling

Source: https://tlaster.github.io/PreCompose/component/navigation.html

Pass and retrieve query string parameters from navigation routes.

```APIDOC
## Query String Handling

### Description
Handles passing and retrieving query string parameters during navigation.

### Passing Query Strings
Pass query strings as part of the route string when calling `navigate`.
```kotlin
navigator.navigate("/detail/123?my=query")
```

### Retrieving Query Strings
Retrieve query string values from the `BackStackEntry`.
```kotlin
scene(route = "/detail/{id}") { backStackEntry ->
    val my: String? = backStackEntry.query<String>("my")
    // Use the retrieved query parameter
}
```

### Retrieving Query String Lists
Use `queryList` for query parameters that may have multiple values.
```kotlin
// Assuming a route like "/list?items=apple&items=banana"
val items: List<String>? = backStackEntry.queryList<String>("items")
```
```

--------------------------------

### Use CounterPresenter with producePresenter

Source: https://tlaster.github.io/PreCompose/component/molecule.html

In your Compose UI, use `producePresenter` to obtain the state from a presenter that handles actions via a lambda.

```kotlin
val state by producePresenter { CounterPresenter() }

```

--------------------------------

### Use CounterPresenter with rememberPresenter

Source: https://tlaster.github.io/PreCompose/component/molecule.html

In your Compose UI, use `rememberPresenter` to connect to the `CounterPresenter`. It returns the state and a channel to send events.

```kotlin
val (state, channel) = rememberPresenter { CounterPresenter(it) }

```

--------------------------------

### Scene Routing

Source: https://tlaster.github.io/PreCompose/component/navigation.html

Defines routes for scenes, supporting static paths, variable path parameters, and regex patterns.

```APIDOC
## Scene Routing

### Description
Defines how to map routes to specific scenes within the navigation graph.

### Static Route
```kotlin
scene(route = "/home") {
    // Scene content
}
```

### Variable Route
```kotlin
scene(route = "/detail/{id}") { backStackEntry ->
    val id: Int? = backStackEntry.path<Int>("id")
    // Scene content using id
}
```

### Optional Variable Route
```kotlin
scene(route = "/detail/{id}?") { backStackEntry ->
    val id: Int? = backStackEntry.path<Int>("id") // id can be null
    // Scene content
}
```

### Regex Route
```kotlin
scene(route = "/detail/{id:[0-9]+}") { backStackEntry ->
    val id: Int? = backStackEntry.path<Int>("id")
    // Scene content
}
```

### Optional Regex Route
```kotlin
scene(route = "/user/{id:[0-9]+}?") { backStackEntry ->
    val id: Int? = backStackEntry.path<Int>("id") // id can be null
    // Scene content
}
```
```

--------------------------------

### ViewModel Implementing State Saving and Restoration

Source: https://tlaster.github.io/PreCompose/component/view_model.html

This ViewModel demonstrates how to use `SavedStateHolder` to save and restore a `MutableStateFlow`. It registers a provider for 'someValue' and consumes it upon restoration.

```kotlin
class SomeViewModel(private val someKey: Int?, savedStateHolder: SavedStateHolder) : ViewModel() {
    val someSavedValue = MutableStateFlow(savedStateHolder.consumeRestored("someValue") as String? ?: "")
    
    init {
        savedStateHolder.registerProvider("someValue") {
            someSavedValue.value
        }
    }
    
    fun setSomeValue(value: String) {
        someSavedValue.value = value
    }
}
```

--------------------------------

### ViewModel with Model Class for Kotlin/Native

Source: https://tlaster.github.io/PreCompose/component/view_model.html

When targeting Kotlin/Native, use the `modelClass` parameter with `viewModel()` to specify the ViewModel class. This ensures proper instantiation.

```kotlin
val viewModel = viewModel(modelClass = SomeViewModel::class, keys = listOf(someKey)) {
    SomeViewModel(someKey)
}
```

--------------------------------

### Define Regex Scene Route

Source: https://tlaster.github.io/PreCompose/component/navigation.html

Defines a scene with a route that uses a regular expression for a path variable. This allows for more complex route matching. The regex follows the colon.

```kotlin
scene(route = "/detail/{id:[0-9]+}") { backStackEntry ->
    val id: Int? = backStackEntry.path<Int>("id")
}
```

--------------------------------

### Define Optional Variable Scene Route

Source: https://tlaster.github.io/PreCompose/component/navigation.html

Defines a scene with an optional path variable. The route will match if the variable is present or absent. Use the '?' suffix for optional variables.

```kotlin
scene(route = "/detail/{id}?") { backStackEntry ->
    val id: Int? = backStackEntry.path<Int>("id")
}
```

--------------------------------

### Group Routing

Source: https://tlaster.github.io/PreCompose/component/navigation.html

Organizes scenes into groups, with static routes for group and initial routes.

```APIDOC
## Group Routing

### Description
Allows grouping of related scenes under a common route. Note that group routes and initial routes do not support path variables or regex.

### Usage
```kotlin
group(route = "/group", initialRoute = "/nestedScreen1") {
    scene(route = "/nestedScreen1") {
        // Content for nested screen 1
    }
    scene(route = "/nestedScreen2") {
        // Content for nested screen 2
    }
}
```
```

--------------------------------

### Retrieve Query String

Source: https://tlaster.github.io/PreCompose/component/navigation.html

Retrieves a query string parameter from the back stack entry. Query strings are passed in the navigation route and accessed via the `query` method.

```kotlin
scene(route = "/detail/{id}") { backStackEntry ->
    val my: String? = backStackEntry.query<String>("my")
}
```

--------------------------------

### Use Koin ViewModel in Compose

Source: https://tlaster.github.io/PreCompose/component/koin.html

Inject and obtain your ViewModel in Compose using the koinViewModel function, passing any required parameters.

```kotlin
val viewModel = koinViewModel<CounterViewModel> { parametersOf(initialCount) }
```

--------------------------------

### Use ViewModel in Compose

Source: https://tlaster.github.io/PreCompose/component/view_model.html

Use the `viewModel()` function to obtain a ViewModel instance within your Compose UI. You can optionally provide keys to manage ViewModel recreation based on state changes.

```kotlin
val viewModel = viewModel(keys = listOf(someKey)) {
    SomeViewModel(someKey)
}
```

--------------------------------

### Define Grouped Scenes

Source: https://tlaster.github.io/PreCompose/component/navigation.html

Groups multiple scenes under a common route prefix. Note that group routes and initialRoutes do not support path variables or regex.

```kotlin
group(route = "/group", initialRoute = "/nestedScreen1") {
    scene(route = "/nestedScreen1") {
        
    }
    scene(route = "/nestedScreen2") {
        
    }
}
```

--------------------------------

### Define ViewModel in Koin Module

Source: https://tlaster.github.io/PreCompose/component/koin.html

Define your ViewModel within a Koin module, specifying any constructor parameters like initialCount.

```kotlin
factory {
    CounterViewModel(
        initialCount = initialCount,
        counterRepository = get(),
    )
}
```

--------------------------------

### Define Variable Scene Route

Source: https://tlaster.github.io/PreCompose/component/navigation.html

Defines a scene with a route that includes a path variable. The variable can be extracted from the back stack entry. Path variables are case-sensitive.

```kotlin
scene(route = "/detail/{id}") { backStackEntry ->
    val id: Int? = backStackEntry.path<Int>("id")
}
```

--------------------------------

### Use Koin ViewModel with vmClass (Kotlin/Native)

Source: https://tlaster.github.io/PreCompose/component/koin.html

For Kotlin/Native targets, use the koinViewModel function with the vmClass parameter, specifying the ViewModel class explicitly.

```kotlin
val viewModel = koinViewModel(vmClass = CounterViewModel::class) { parametersOf(initialCount) }
```

--------------------------------

### ViewModel with SavedStateHolder

Source: https://tlaster.github.io/PreCompose/component/view_model.html

Integrate `SavedStateHolder` to enable saving and restoring state within your ViewModel. Register providers for state keys and consume restored values.

```kotlin
val viewModel = viewModel(modelClass = SomeViewModel::class, keys = listOf(someKey)) {
    SomeViewModel(someKey, savedStateHolder)
}
```

--------------------------------

### Navigator API

Source: https://tlaster.github.io/PreCompose/component/navigation.html

The Navigator object replaces Jetpack Navigation's NavController, providing methods to navigate between routes and manage the back stack.

```APIDOC
## Navigator API

### Description
Provides methods for navigating between scenes and checking navigation status.

### Methods
* `navigate(route: String, options: NavOptions? = null)`: Navigates to a specified route with optional navigation options.
* `goBack()`: Attempts to navigate up in the navigation hierarchy.
* `canGoBack: Boolean`: Returns true if the navigator can navigate up, false otherwise.

### Example Usage
```kotlin
// Navigate to a new route
navigator.navigate("/home")

// Navigate with options
navigator.navigate("/home", NavOptions(launchSingleTop = true))

// Go back
navigator.goBack()

// Check if back navigation is possible
if (navigator.canGoBack) {
    // ...
}
```
```
Tokens:
Raw