vice
1.0.8indexedKMP MVI framework built on Compose, facilitating modern application architecture with streamlined state management and intuitive UI updates.
162
Stars
—
Used by
dependents
—
Health
/ 100
KMP MVI framework built on Compose, facilitating modern application architecture with streamlined state management and intuitive UI updates.
VICE is an MVI (Model-View-Intent) framework that uses UDF (Unidirectional Data Flow) to drive a UI:
graph LR;
Compositor-- composites ViewState --->View
View-- emits Intent --->Compositor
It supports all KMP targets that are supported by Compose Multiplatform.
repositories {
mavenCentral()
}
dependencies {
implementation("com.eygraber:vice-core:1.0.8")
implementation("com.eygraber:vice-nav:1.0.8")
}
Snapshots can be found here.
The advantages of VICE are:
There are 5 main components of VICE:
These are all wired together using a ViceContainer. Calling ViceContainer.Vice() kicks off the UDF loop, and
everything after that is managed through the VICE components.
The ViceView is a Composable function that takes 2 parameters:
ViewState - an immutable class representing the state of the View at the current momentonIntent - a function for emitting Intent that correspond to user interactionstypealias ViceView<Intent, State> = @Composable (State, (Intent) -> Unit) -> Unit
As the user interacts with the ViceView it emits a corresponding Intent using the onIntent callback.
TheViceCompositor reacts to the Intent by performing an action and/or changing the ViewState.
To leverage the performance benefits of Compose's function skipping, the ViceView is broken up into many smaller
Composable functions. These functions only receive the parts of the ViewState that they need to
render themselves, and pass events back up through the use of callback lambdas. As the ViewState changes causing the
ViceView to recompose, only those functions that have parameters with new values will be called. The others will be
skipped, and Compose will use their most recent emission to create the next UI frame.
For this to work, Compose Stability needs to be taken into account. For that reason, it is suggested that
ViewState be an @Immutable data class.
However keep in mind that your use case might differ23
@Immutable
data class SampleViewState(
val title: String,
val buttonLabel: String,
val bottomNavItems: List<String>,
)
typealias SampleView = (SampleViewState, (SampleIntent) -> ) ->
{
Scaffold(
topBar = { SampleTopBar(state.title) },
bottomBar = { SampleBottomBar(state.bottomNavItems) }
) { contentPadding ->
Box(modifier = Modifier.padding(contentPadding)) {
SampleButton(
onClick = { onIntent(SampleIntent.ButtonClicked) },
label = state.buttonLabel,
)
}
}
}
Intent models an action that the user has taken (e.g. clicked a button, entered text, acknowledged a dialog, etc...).
It will usually be a sealed hierarchy or enum class.
If you want to throttle the rate that your Intent can be emitted, have it implement ThrottlingIntent.
By default it will only allow one Intent with a matching this::class to emit every 500 milliseconds.
If you want to implement your own custom behavior for an Intent, create an implementation of ViceIntentFilter
and add it to your ViceContainer when creating it.
[!NOTE]
ThrottlingIntentFilteris added toViceContainerby default. If you provide your ownViceIntentFilterand you wantThrottlingIntentFilterto be used as well you'll have to manually include it.
The ViceCompositor combines data into a ViewState.
Instead of the traditional way of combining this data (e.g. using a kotlinx.coroutines.flow.combine function),
the ViceCompositor leverages Compose's Snapshots to allow working with the data in a more natural, imperative manner.
Borrowing from Molecule's introduction:
Using combine:
combine(
db.users().onStart { emit(null) },
db.balances().onStart { emit(0L) },
) { user, balance ->
when(user) {
null -> Loading
else -> Data(user.name, balance)
}
}
vs
Using Compose:
val user by userFlow.collectAsStateWithLifecycle(null)
val balance by balanceFlow.collectAsStateWithLifecycle(0L)
when(user) {
null -> Loading
else -> Data(user.name, balance)
}
[!TIP]
Flow.collectAsStateWithLifecycleis the suggested way to collect aFlowin Compose5
ViceSource aims to make it simple to provide data to a ViceCompositor:
interface ViceSource<T> {
@Composable
fun currentState(): T
}
currentState() can be backed by any source that can cause the function to recompose when data is changed.
It should provide a single piece of data for the ViewState, and should be read in ViceCompositor.composite
in order to create the ViewState.
There are several implementations provided by VICE that cover common use cases.
StateSource simply makes ViceSource implement Compose's State type, and by default provides [currentState]
with its value.
StateSource can be used instead of the other State based sources if the stricter rules of an abstract class aren't needed.
StateSource can also be used to define a custom interface, and abstract
implementors of it (e.g. MutableStateSource, etc...) can be used to provide the implementation.
MutableViceSource allows for imperative updates to its state. It provides an update function to
change its current state. It is the foundation for several other specific MutableViceSource types.
It is primarily meant to be used when a full implementation (e.g. MutableStateSource) isn't warranted,
but a state holder is needed outside of a composable context.
MutableViceSource has several implementations available, each created using a top-level function:
mutableViceSourcesaveableMutableStateSourceserializableMutableStateSourcemutableViceSource is the basic implementation that wraps a MutableState.
saveableMutableViceSource will automatically save and restore its state across
process death and configuration changes. You can optionally provide a custom Saver.
serializableMutableViceSource uses kotlinx.serialization to save and restore its state.
To use this, your state will need to be serializable.
val source = mutableViceSource("Hello")
val saveableSource = saveableMutableViceSource(0)
val serializableSource = serializableMutableStateSource(MyData("test"))
To avoid boxing, there are specific MutableViceSource implementations for primitive types.
These can be created using the corresponding top-level functions:
mutableIntSource(initial)mutableLongSource(initial)mutableFloatSource(initial)mutableDoubleSource(initial)To make them saveable, use the isSaveable parameter in their creation functions.
val source = mutableFloatSource(0F, isSaveable = true)
MutableStateSource wraps a MutableState, and provides an update function for implementations to
mutate it. Useful for encapsulating behavior around the MutableState instead of managing it in the ViceCompositor.
internal {
None : MyFeatureDialogState
( message: String) : MyFeatureDialogState
}
: <>() {
initial = MyFeatureDialogState.None
{
update(MyFeatureDialogState.None)
}
{
update(
MyFeatureDialogState.Error(message)
)
}
}
SaveableMutableStateSource is the same as MutableStateSource except it wraps its internal State in a
rememberSaveable call.
internal class MyCounterSource : SaveableMutableStateSource<Int>() {
override val initial = 0
fun reset() {
update(0)
}
fun increment() {
update(value + 1)
}
}
SerializableMutableStateSource is the same as MutableStateSource except it wraps its internal State in a
rememberSerializable call.
@Serializable
data class Counter(val count: Int)
internal class : <>() {
initial = Counter()
{
update(Counter())
}
{
update(count.value + )
}
}
DerivedStateSource is similar to MutableStateSource, but encapsulates the content of a derivedStateOf call:
internal class MyDerivedStateSource(
private val fastChangingStateSource: FastChangingStateSource,
) : DerivedStateSource<MyDerivedState>() {
override fun deriveState(): MyDerivedState {
val fastChangingState fastChangingStateSource
fastChangingState.transformIntoSomethingElse()
}
: MyDerivedState {
TODO()
}
}
LoadableSource is similar to a MutableStateSource, but allows you to differentiate between
an initial placeholder value, and future value that will be loaded asynchronously. If the value doesn't load
within a (configurable) amount of time, then there will be a (configurable) delay before the value is set as the state
(so that there isn't a "flash" when transitioning from the placeholder to the actual data).
This can be very powerful when combined with a skeleton loading UI like Compose Placeholder.
FlowSource is backed by a Flow<T> and an initial: T and recomposes whenever the Flow emits.
internal class MyFlowSource(
private val featureRepo: MyFeatureRepository,
) : FlowSource<List<MyFeatureData>>() {
override val initial = emptyList()
override val flow = featureRepo
.dataFlow
.map { dataList ->
dataList.map(::MyFeatureData)
}
}
LoadableFlowSource is similar to a FlowSource, but allows you to differentiate between
an initial placeholder value, and future values emitted from the provided Flow. If the Flow
doesn't emit within a (configurable) amount of time, then any emissions for a (configurable) amount of time
after that will be delayed (so that there isn't a "flash" when transitioning from the placeholder to the actual data).
This can be very powerful when combined with a skeleton loading UI like Compose Placeholder.
StateFlowSource is backed by a StateFlow<T> and a onAttached function that receives a CoroutineScope that
allows you to modify the StateFlow (which is usually implemented as a MutableStateFlow).
internal class TimerFlowSource : StateFlowSource<Int>() {
override val flow = MutableStateFlow(0)
override suspend fun onAttached(scope: CoroutineScope) {
i =
(isActive) {
flow.value = i++
delay(seconds)
}
}
}
It can also function as a way to encapsulate external mutations to the StateFlow:
ViceEffects handle non UI related tasks, like analytics, lifecycle handling, etc…
There is a convenient no-op implementation available at ViceEffects.None.
class WelcomeScreenEffects(
private val analytics: Analytics,
private val lifecycle: Lifecycle,
) : ViceEffects() {
override fun CoroutineScope.runEffects() {
launch {
lifecycle.repeatOnLifecycle(Lifecycle.State.RESUMED) {
analytics.trackResumeWelcomeScreen()
}
}
}
}
Let's take a look at a simple example:
VICE has an integration with AndroidX Navigation Compose that provides a ViceDestination and NavGraphBuilder
extensions to simplify setting up a Navigation Compose destination.
LocalAnimatedVisibilityScope provides the AnimatedVisibilityScope from the NavGraphBuilder.destination calls
to simplify working with Compose Shared Element Transitions.
You need to wrap your NavHost in SharedTransitionLayout for this to work:
SharedTransitionLayout {
CompositionLocalProvider(
LocalSharedTransitionScope provides this
) {
NavHost(...) {
viceComposable<Routes.Home> {
...
}
}
}
}
You can now use shared element transition APIs more easily in your ViceView:
@Composable
fun HomeView(
state: HomeState,
onIntent: (HomeIntent) -> Unit,
) {
Box(
modifier = Modifier
.sharedElement(
sharedTransitionScope = LocalSharedTransitionScope.current,
animatedVisibilityScope = LocalAnimatedVisibilityScope.current,
state = rememberSharedContentState("foo")
)
)
}
internal sealed interface MyFeatureDialogState {
data object None : MyFeatureDialogState
data class Error(val message: String) : MyFeatureDialogState
}
internal class MyFeatureDialogSource : StateSource<MyFeatureDialogState> {
override var value: MyFeatureDialogState by mutableStateOf(MyFeatureDialogState.None)
private set
fun clearError() {
value = MyFeatureDialogState.None
}
fun showError(message: String) {
value = MyFeatureDialogState.Error(message)
}
}
internal sealed interface MyFeatureDialogState {
data object None : MyFeatureDialogState
data class Error(val message: String) : MyFeatureDialogState
}
internal interface MyFeatureDialogSource : StateSource<MyFeatureDialogState>
internal class RealMyFeatureDialogSource : MyFeatureDialogSource, MutableStateSource<MyFeatureDialogState>() {
override val initial = MyFeatureDialogState.None
fun clearError() {
update(MyFeatureDialogState.None)
}
fun showError(message: String) {
update(
MyFeatureDialogState.Error(message)
)
}
}
class TodoItemsSource(
db: MyDatabase,
) : LoadableSource<List<TodoItem>>() {
override val placeholder = listOf(
TodoItem(
id = "placeholder",
title = "_".repeat(20),
description = "_".repeat(75),
)
)
suspend fun load() =
db
.todoItemQueries
.findAll()
}
data class TodoItemsViewState(
val items: Loadable<List<TodoItem>>,
)
fun TodoListView(
state: TodoItemsViewState,
onIntent: (TodoItemsIntent) -> Unit,
) {
lazyColumn {
items(
items = state.items.value,
key = { it.id },
) { todoItem ->
Column {
Text(
text = todoItem.title,
modifier = Modifier.placeholder(visible = state.items.isLoading)
)
Text(
text = todoItem.description,
modifier = Modifier.placeholder(visible = state.items.isLoading)
)
}
}
}
}
class TodoItemsSource(
db: MyDatabase,
) : LoadableFlowSource<List<TodoItem>>() {
override val placeholder = listOf(
TodoItem(
id = "placeholder",
title = "_".repeat(20),
description = "_".repeat(75),
)
)
override val dataFlow =
db
.todoItemQueries
.findAll()
.asFlow()
.mapToList()
}
data class TodoItemsViewState(
val items: Loadable<List<TodoItem>>,
)
fun TodoListView(
state: TodoItemsViewState,
onIntent: (TodoItemsIntent) -> Unit,
) {
lazyColumn {
items(
items = state.items.value,
key = { it.id },
) { todoItem ->
Column {
Text(
text = todoItem.title,
modifier = Modifier.placeholder(visible = state.items.isLoading)
)
Text(
text = todoItem.description,
modifier = Modifier.placeholder(visible = state.items.isLoading)
)
}
}
}
}
internal sealed interface TimerState {
data object Reset : TimerState
data class Running(val secondsRemaining: Int) : TimerState
data object Finished : TimeState
}
internal class TimerFlowSource : StateFlowSource<TimerState> {
override val flow = MutableStateFlow(TimerState.Reset)
override suspend fun onAttached(scope: CoroutineScope) {
var i = 0
while(isActive) {
flow.value = i++
delay(1.seconds)
}
}
}
sealed interface GreetingIntent {
data object SaidHello : GreetingIntent, ThrottlingIntent
}
data class GreetingState(
val greeting: String?,
)
fun GreetingView(state: GreetingState, onIntent: (GreetingIntent) -> Unit) {
Column {
if(state.greeting != null) {
Text(state.greeting)
}
Button(
onClick = { onIntent(GreetingIntent.SaidHello) },
) {
Text("Say Hello")
}
}
}
class GreetingCompositor : ViceCompositor {
// remember isn't needed since we're not in a Composable context
private var greeting by mutableStateOf<String>(null)
override fun composite() = GreetingState(
greeting = greeting,
)
override suspend fun onIntent(intent: GreetingIntent) {
when(intent) {
GreetingIntent.SaidHello -> greeting = "Hello!"
}
}
}
sealed interface HomeIntent {
data object AddItem : HomeIntent
data class ToggleItemCompletion(val item: TodoItem) : HomeIntent
data class NavigateToDetails(val id: String) : HomeIntent
data object NavigateToSettings : HomeIntent
}
data class HomeViewState(
val items: List<TodoItem>,
)
typealias HomeView = (HomeViewState, (HomeIntent) -> Unit) -> Unit
fun HomeView(
state: HomeViewState,
onIntent: (HomeIntent) -> Unit,
) {
TODO()
}
class HomeCompositor(
private val onNavigateToCreateItem: () -> Unit,
private val onNavigateToUpdateItem: (String) -> Unit,
private val onNavigateToSettings: () -> Unit,
) : ViceCompositor<HomeIntent, HomeViewState> {
override fun composite() = HomeViewState(
items = TodoRepo.items.collectAsState().value,
)
override suspend fun onIntent(intent: HomeIntent) {
when(intent) {
HomeIntent.AddItem -> onNavigateToCreateItem()
is HomeIntent.ToggleItemCompletion -> TodoRepo.updateItem(
newItem = intent.item.copy(
completed = !intent.item.completed,
),
)
is HomeIntent.NavigateToDetails -> onNavigateToUpdateItem(intent.id)
HomeIntent.NavigateToSettings -> onNavigateToSettings()
}
}
}
class HomeDestination(
onNavigateToCreateItem: () -> Unit,
onNavigateToUpdateItem: (String) -> Unit,
onNavigateToSettings: () -> Unit,
) : ViceDestination<HomeIntent, HomeCompositor, ViceEffects, HomeViewState>() {
override val view: HomeView = { state, onIntent -> HomeView(state, onIntent) }
override val compositor = HomeCompositor(
onNavigateToCreateItem,
onNavigateToUpdateItem,
onNavigateToSettings,
)
override val effects = ViceEffects.None
}
Surfaced from shared tags and platforms — no rankings paid for.