Skill v1.0.0

// CORRECT — lifecycle-aware + stable UiState → composables can skip
@Composable
fun CoursesScreen(viewModel: CoursesViewModel = hiltViewModel()) {
    // collectAsStateWithLifecycle: stops collection when lifecycle is STOPPED
    // (app backgrounded, screen off) — saves CPU and battery
    val uiState by viewModel.uiState.collectAsStateWithLifecycle()
    CoursesContent(state = uiState, onAction = viewModel::onAction)
}
 
// Stable UiState: all val properties + ImmutableList → composables are skippable
@Immutable
data class CoursesUiState(
    val isLoading: Boolean = false,
    val courses: ImmutableList<CourseUi> = persistentListOf(), // kotlinx.collections.immutable
    val error: String? = null,
)
 
// WRONG — collectAsState collects forever AND mutable List makes composables non-skippable
@Composable
fun CoursesScreen(viewModel: CoursesViewModel = hiltViewModel()) {
    // collectAsState: collects even when app is backgrounded → wasted CPU/battery
    val uiState by viewModel.uiState.collectAsState()
    CoursesContent(state = uiState, onAction = viewModel::onAction)
}
 
// Unstable UiState: var property → whole class inferred unstable → composables never skip
data class CoursesUiState(
    var isLoading: Boolean = false,       // var = UNSTABLE
    val courses: List<CourseUi> = emptyList(), // mutable List = UNSTABLE
)

// CORRECT
val uiState by viewModel.uiState.collectAsStateWithLifecycle()
 
// WRONG — collects forever
val uiState by viewModel.uiState.collectAsState()

val uiState: StateFlow<CoursesUiState> = someFlow
    .stateIn(
        scope = viewModelScope,
        started = SharingStarted.WhileSubscribed(5_000), // 5 s timeout survives rotation
        initialValue = CoursesUiState(),
    )

// CORRECT — framework-decoupled, testable
@HiltViewModel
class CoursesViewModel @Inject constructor(
    private val loadCourses: LoadCoursesUseCase,
) : ViewModel() { ... }
 
// WRONG — couples ViewModel to Android framework, makes testing harder
class CoursesViewModel(application: Application) : AndroidViewModel(application) { ... }

// CORRECT
@Composable
fun CoursesScreen(viewModel: CoursesViewModel = hiltViewModel()) {
    val uiState by viewModel.uiState.collectAsStateWithLifecycle()
    CoursesContent(state = uiState, onAction = viewModel::onAction)
}
 
@Composable
fun CoursesContent(state: CoursesUiState, onAction: (CoursesAction) -> Unit) { ... }
 
// WRONG — child receives ViewModel
@Composable
fun CourseCard(viewModel: CoursesViewModel) { ... } // cannot preview or test in isolation

// CORRECT — navigation modelled as state
data class CoursesUiState(
    val navigateToCourseId: String? = null, // null = no navigation pending
    ...
)
 
// WRONG — event lost if UI resubscribes before consuming
private val _navigationEvent = MutableSharedFlow<String>()
val navigationEvent: SharedFlow<String> = _navigationEvent

// CORRECT — fully stable
@Immutable
data class CourseUi(
    val id: String,
    val title: String,
    val isBookmarked: Boolean,
)
 
@Immutable
data class CoursesUiState(
    val courses: ImmutableList<CourseUi> = persistentListOf(),
    val isLoading: Boolean = false,
)
 
// WRONG — var makes the whole class unstable
data class CoursesUiState(
    var isLoading: Boolean = false, // var = unstable
    val courses: List<CourseUi> = emptyList(), // mutable List = unstable
)

// CORRECT — pass lambda; scroll position read only in child scope
@Composable
fun Parent() {
    val listState = rememberLazyListState()
    Child(firstVisibleIndex = { listState.firstVisibleItemIndex })
}
 
@Composable
fun Child(firstVisibleIndex: () -> Int) {
    val index = firstVisibleIndex() // read deferred to this scope
}
 
// WRONG — parent reads and passes the value → parent recomposes on every scroll event
@Composable
fun Parent() {
    val listState = rememberLazyListState()
    Child(firstVisibleIndex = listState.firstVisibleItemIndex) // read HERE = parent recomposes
}

@Stable
class MapState {
    private val _location = mutableStateOf<Position?>(null)
    val latitude by derivedStateOf { _location.value?.latitude }
    val longitude by derivedStateOf { _location.value?.longitude }
 
    fun changeLocation(position: Position) {
        _location.value = position
    }
}
 
@Composable
fun rememberMapState(): MapState = remember { MapState() }

// SCREEN — connects to ViewModel, handles navigation
@Composable
fun CoursesScreen(
    viewModel: CoursesViewModel = hiltViewModel(),
    onOpenCourse: (String) -> Unit,
) {
    val uiState by viewModel.uiState.collectAsStateWithLifecycle()
    CoursesContent(
        state = uiState,
        onAction = viewModel::onAction,
        onCourseClick = onOpenCourse,
        modifier = Modifier.fillMaxSize(),
    )
}
 
// CONTENT — pure, previewable, testable
@Composable
fun CoursesContent(
    state: CoursesUiState,
    onAction: (CoursesAction) -> Unit,
    onCourseClick: (String) -> Unit,
    modifier: Modifier = Modifier,
) {
    // Only renders — no ViewModel access
}

// CORRECT — atomic under concurrency
_uiState.update { it.copy(isLoading = false, courses = newCourses) }
 
// WRONG — race condition possible
_uiState.value = _uiState.value.copy(isLoading = false, courses = newCourses)

@HiltViewModel
class CoursesViewModel @Inject constructor(
    private val loadCourses: LoadCoursesUseCase,
) : ViewModel() {
 
    private val _uiState = MutableStateFlow(CoursesUiState())
    val uiState: StateFlow<CoursesUiState> = _uiState
        .stateIn(viewModelScope, SharingStarted.WhileSubscribed(5_000), CoursesUiState())
 
    fun onAction(action: CoursesAction) {
        when (action) {
            is CoursesAction.BookmarkClicked -> toggleBookmark(action.id)
            CoursesAction.RetryClicked -> loadCourses()
        }
    }
 
    private fun toggleBookmark(courseId: String) {
        _uiState.update { state ->
            state.copy(
                courses = state.courses.map { course ->
                    if (course.id == courseId) course.copy(isBookmarked = !course.isBookmarked)
                    else course
                }.toPersistentList()
            )
        }
    }
}

@Immutable
data class CoursesState(
    val isLoading: Boolean = false,
    val courses: ImmutableList<CourseUi> = persistentListOf(),
    val error: String? = null,
)
 
sealed interface CoursesIntent {
    data object Load : CoursesIntent
    data class BookmarkClicked(val id: String) : CoursesIntent
}
 
sealed interface CoursesChange {
    data object Loading : CoursesChange
    data class Data(val courses: List<CourseUi>) : CoursesChange
    data class Failure(val message: String) : CoursesChange
}
 
private fun CoursesState.reduce(change: CoursesChange): CoursesState = when (change) {
    CoursesChange.Loading -> copy(isLoading = true, error = null)
    is CoursesChange.Data -> copy(isLoading = false, courses = change.courses.toPersistentList(), error = null)
    is CoursesChange.Failure -> copy(isLoading = false, error = change.message)
}

// Sealed hierarchy allows passing subtype lambda to child — no extra wrappers needed
sealed class CoursesAction {
    sealed class Header : CoursesAction() {
        data object Refresh : Header()
    }
    sealed class Item : CoursesAction() {
        data class BookmarkClicked(val id: String) : Item()
        data class CourseClicked(val id: String) : Item()
    }
}
 
// CourseCard receives (CoursesAction.Item) -> Unit — a subtype of (CoursesAction) -> Unit
@Composable
fun CourseCard(
    model: CourseUi,
    onAction: (CoursesAction.Item) -> Unit,
    modifier: Modifier = Modifier,
) { ... }

// Each composable section receives only its slice — no over-passing
@Immutable
data class UserProfileUiState(
    val header: Header,
    val details: Details,
) {
    @Immutable
    data class Header(val fullName: String, val avatarUrl: String?)
 
    @Immutable
    data class Details(val followersCount: Int, val bio: String)
}

// Lifecycle-aware state collection
implementation("androidx.lifecycle:lifecycle-runtime-compose:2.8.+")
 
// Stable collections for UiState
implementation("org.jetbrains.kotlinx:kotlinx-collections-immutable:0.3.7")
 
// Hilt ViewModel injection (androidMain only — Android-only)
implementation("com.google.dagger:hilt-android:2.51.+")
kapt("com.google.dagger:hilt-compiler:2.51.+")
implementation("androidx.hilt:hilt-navigation-compose:1.2.+")
 
// CMP: Koin alternative for commonMain DI
// implementation("io.insert-koin:koin-compose-viewmodel:3.5+")
// implementation("io.insert-koin:koin-core:3.5+")
 
// CMP: multiplatform ViewModel + lifecycle (lifecycle-viewmodel-compose 2.10.0)
// implementation("org.jetbrains.androidx.lifecycle:lifecycle-viewmodel-compose:2.10.0")