@mmerterden/multi-agent-pipeline 20.0.0 → 20.2.0

package/pipeline/skills/shared/external/android-mvi-viewmodel/references/patterns.md

@@ -0,0 +1,257 @@
+# Android MVI BaseViewModel Patterns
+
+Full code examples backing the guidance in `SKILL.md`. Load this file when you
+need a complete implementation to adapt. Headings mirror the SKILL.md sections.
+
+## Contents
+
+- [Assembled BaseViewModel](#assembled-baseviewmodel)
+- [MVI contracts for a screen](#mvi-contracts-for-a-screen)
+- [A concrete ViewModel](#a-concrete-viewmodel)
+- [Lifecycle-aware event collector](#lifecycle-aware-event-collector)
+- [Stateless screen composable](#stateless-screen-composable)
+- [Testing the ViewModel](#testing-the-viewmodel)
+
+## Assembled BaseViewModel
+
+The complete base class combining state, events, intent dispatch, the use-case
+executor, reference-counted loading, and the job registry.
+
+```kotlin
+import androidx.lifecycle.ViewModel
+import androidx.lifecycle.viewModelScope
+import kotlinx.coroutines.CancellationException
+import kotlinx.coroutines.Job
+import kotlinx.coroutines.channels.Channel
+import kotlinx.coroutines.flow.Flow
+import kotlinx.coroutines.flow.MutableStateFlow
+import kotlinx.coroutines.flow.SharingStarted
+import kotlinx.coroutines.flow.StateFlow
+import kotlinx.coroutines.flow.asStateFlow
+import kotlinx.coroutines.flow.map
+import kotlinx.coroutines.flow.receiveAsFlow
+import kotlinx.coroutines.flow.stateIn
+import kotlinx.coroutines.flow.update
+import kotlinx.coroutines.launch
+
+abstract class BaseViewModel<State, Intent, Event>(
+    initialState: State,
+) : ViewModel() {
+
+    private val _state = MutableStateFlow(initialState)
+    val state: StateFlow<State> = _state.asStateFlow()
+
+    private val _events = Channel<Event>(Channel.RENDEZVOUS)
+    val events: Flow<Event> = _events.receiveAsFlow()
+
+    private val loadingCount = MutableStateFlow(0)
+    val isLoading: StateFlow<Boolean> =
+        loadingCount
+            .map { it > 0 }
+            .stateIn(viewModelScope, SharingStarted.Eagerly, false)
+
+    private val jobs = mutableMapOf<String, Job>()
+
+    fun processIntent(intent: Intent) = handleIntent(intent)
+
+    protected abstract fun handleIntent(intent: Intent)
+
+    protected open fun routeError(throwable: Throwable) = Unit
+
+    protected fun reduce(reducer: State.() -> State) {
+        _state.update { it.reducer() }
+    }
+
+    protected fun sendEvent(event: Event) {
+        viewModelScope.launch { _events.send(event) }
+    }
+
+    protected fun <T> execute(
+        showLoading: Boolean = true,
+        onError: ((Throwable) -> Unit)? = null,
+        block: suspend () -> T,
+        onSuccess: (T) -> Unit,
+    ): Job = viewModelScope.launch {
+        if (showLoading) incrementLoading()
+        try {
+            runCatching { block() }
+                .onSuccess(onSuccess)
+                .onFailure { throwable ->
+                    if (throwable is CancellationException) throw throwable
+                    (onError ?: ::routeError)(throwable)
+                }
+        } finally {
+            if (showLoading) decrementLoading()
+        }
+    }
+
+    protected fun launchTracked(key: String, block: suspend () -> Unit): Job {
+        jobs.remove(key)?.cancel()
+        return viewModelScope.launch { block() }.also { jobs[key] = it }
+    }
+
+    protected fun cancel(key: String) {
+        jobs.remove(key)?.cancel()
+    }
+
+    private fun incrementLoading() = loadingCount.update { it + 1 }
+
+    private fun decrementLoading() =
+        loadingCount.update { (it - 1).coerceAtLeast(0) }
+
+    override fun onCleared() {
+        jobs.values.forEach { it.cancel() }
+        jobs.clear()
+        super.onCleared()
+    }
+}
+```
+
+## MVI contracts for a screen
+
+State is the render model, Intent is every input, Event is every one-shot
+effect. Keep all three next to the screen they serve.
+
+```kotlin
+@Immutable
+data class SearchState(
+    val query: String = "",
+    val results: List<ResultItem> = emptyList(),
+    val error: String? = null,
+)
+
+sealed interface SearchIntent {
+    data class QueryChanged(val text: String) : SearchIntent
+    data object Submit : SearchIntent
+    data object Retry : SearchIntent
+}
+
+sealed interface SearchEvent {
+    data class OpenDetail(val id: Id) : SearchEvent
+    data class ShowError(val message: String) : SearchEvent
+}
+```
+
+## A concrete ViewModel
+
+The subclass supplies the initial state, implements the exhaustive `when`, and
+uses the inherited helpers - no coroutine, loading, or error boilerplate.
+
+```kotlin
+@HiltViewModel
+class SearchViewModel @Inject constructor(
+    private val search: SearchUseCase,
+) : BaseViewModel<SearchState, SearchIntent, SearchEvent>(SearchState()) {
+
+    override fun handleIntent(intent: SearchIntent) = when (intent) {
+        is SearchIntent.QueryChanged -> reduce { copy(query = intent.text) }
+        SearchIntent.Submit -> runSearch()
+        SearchIntent.Retry -> runSearch()
+    }
+
+    private fun runSearch() {
+        val query = state.value.query
+        launchTracked("search") {
+            execute(
+                block = { search(query) },
+                onError = { sendEvent(SearchEvent.ShowError(it.toUserMessage())) },
+                onSuccess = { results -> reduce { copy(results = results, error = null) } },
+            )
+        }
+    }
+
+    override fun routeError(throwable: Throwable) {
+        sendEvent(SearchEvent.ShowError(throwable.toUserMessage()))
+    }
+}
+```
+
+Keying `launchTracked("search")` makes each new submit cancel the previous
+in-flight request automatically.
+
+## Lifecycle-aware event collector
+
+Collect one-shot events only while the screen is at least `STARTED`, so a
+backgrounded screen never consumes a navigation. `flowWithLifecycle` restarts
+collection across stop/start without leaking the previous coroutine.
+
+```kotlin
+@Composable
+fun <Event> ObserveEvents(
+    events: Flow<Event>,
+    lifecycleOwner: LifecycleOwner = LocalLifecycleOwner.current,
+    onEvent: (Event) -> Unit,
+) {
+    LaunchedEffect(events, lifecycleOwner) {
+        events
+            .flowWithLifecycle(lifecycleOwner.lifecycle, Lifecycle.State.STARTED)
+            .collect(onEvent)
+    }
+}
+```
+
+## Stateless screen composable
+
+The screen receives a state value and lambdas only. It has no ViewModel
+reference, so it renders in a `@Preview` and in tests without Hilt.
+
+```kotlin
+@Composable
+fun SearchScreen(
+    state: SearchState,
+    isLoading: Boolean,
+    onIntent: (SearchIntent) -> Unit,
+) {
+    Column {
+        SearchField(
+            value = state.query,
+            onValueChange = { onIntent(SearchIntent.QueryChanged(it)) },
+            onSubmit = { onIntent(SearchIntent.Submit) },
+        )
+        when {
+            isLoading -> LoadingIndicator()
+            state.error != null -> ErrorState(
+                message = state.error,
+                onRetry = { onIntent(SearchIntent.Retry) },
+            )
+            else -> ResultList(items = state.results)
+        }
+    }
+}
+```
+
+## Testing the ViewModel
+
+Drive intents, assert on state with Turbine, and assert one-shot events on the
+`events` flow. Use a `TestDispatcher` so `viewModelScope` is controllable.
+
+```kotlin
+@Test
+fun submit_emitsResults() = runTest {
+    val viewModel = SearchViewModel(FakeSearchUseCase(results = sample))
+
+    viewModel.state.test {
+        assertEquals(SearchState(), awaitItem())
+
+        viewModel.processIntent(SearchIntent.QueryChanged("abc"))
+        assertEquals("abc", awaitItem().query)
+
+        viewModel.processIntent(SearchIntent.Submit)
+        assertEquals(sample, awaitItem().results)
+    }
+}
+
+@Test
+fun useCaseFailure_emitsShowErrorEvent() = runTest {
+    val viewModel = SearchViewModel(FakeSearchUseCase(error = IOException()))
+
+    viewModel.events.test {
+        viewModel.processIntent(SearchIntent.Submit)
+        assertIs<SearchEvent.ShowError>(awaitItem())
+    }
+}
+```
+
+Set the main dispatcher to a `StandardTestDispatcher` in `@Before` /
+`Dispatchers.setMain(...)` and reset it in `@After` so `viewModelScope`
+coroutines run under test control.