Compose Agent Skill

What is SubcomposeLayout?

SubcomposeLayout is an analogue of Layout that allows you to subcompose content during the measurement stage. This enables you to use values calculated during measurement (like child sizes or parent constraints) as parameters for the composition of children.

Common Use Cases

• Constraint-dependent composition: When you need to know the constraints passed by a parent during composition and cannot solve the problem with a standard Layout or LayoutModifier (e.g., BoxWithConstraints).
• Inter-child dependency: When the size of one child must be known to compose a second child.
• Lazy composition: Composing items lazily based on available size (e.g., a list where only visible items are composed).

Usage

You can use the simple overload which manages its own state, or provide a SubcomposeLayoutState for more control.

SubcomposeLayout(
    modifier = Modifier,
    measurePolicy = { constraints ->
        // Perform subcomposition and measurement here
        layout(constraints.maxWidth, constraints.maxHeight) { /* ... */ }
    }
)

@Composable
fun SubcomposeLayout(
    modifier: Modifier = Modifier,
    measurePolicy: SubcomposeMeasureScope.(Constraints) -> MeasureResult,
) {
    // ...
}

Follow these rules to prevent common state-related crashes and architectural issues in production:

1. ViewModel State: Use StateFlow (via MutableStateFlow) in ViewModels. Never use mutableStateOf in a ViewModel, as it couples the business logic to the Compose runtime.
2. UI Events: Use SharedFlow with extraBufferCapacity = 1 and onBufferOverflow = BufferOverflow.DROP_OLDEST for UI events. Avoid Channel for events, as they can drop events during lifecycle transitions.
3. Saved State: Use rememberSaveable only at the screen/NavGraph level. Avoid using it inside individual list items to prevent TransactionTooLargeException due to excessive Bundle size.
4. Reactive Scrolling: Use snapshotFlow combined with distinctUntilChanged() to monitor scroll positions or other snapshot states. Never poll state in a recomposition loop.
5. Derived Flows: Use .map() on repository flows and convert them to state using .stateIn() with SharingStarted.WhileSubscribed(5_000) to handle configuration changes gracefully.

// Rule 1: ViewModel State
class ProfileViewModel : ViewModel() {
    private val _name = MutableStateFlow("")
    val name: StateFlow<String> = _name.asStateFlow()
}

// Rule 2: SharedFlow for Events
class OrderViewModel : ViewModel() {
    private val _events = MutableSharedFlow<UiEvent>(
        extraBufferCapacity = 1,
        onBufferOverflow = BufferOverflow.DROP_OLDEST
    )
    val events = _events.asSharedFlow()
}

// Rule 4: Reactive Scroll
LaunchedEffect(listState) {
    snapshotFlow { listState.firstVisibleItemIndex }
        .distinctUntilChanged()
        .collect { index -> /* side effect */ }
}

// Rule 5: Derived Flows
val uiState: StateFlow<DashboardUiState> = repository.dashboardData
    .map { data -> DashboardUiState(...) }
    .stateIn(
        scope = viewModelScope,
        started = SharingStarted.WhileSubscribed(5_000),
        initialValue = DashboardUiState()
    )

Compose Foundation uses a nested scrolling system to allow multiple scrollable components to coordinate movement. When a scroll or fling occurs, the system uses a NestedScrollScope to manage how much of a delta is consumed by the current node versus how much is passed to parent nodes.

Key mechanisms include:

• scroll function: Opens a scrolling session that supports nested scrolling and overscroll. It provides a NestedScrollScope to the block.
• onPostScroll: A hook in NestedScrollConnection used to handle remaining scroll deltas after a child has consumed what it can.
• onPostFling: A hook used to handle leftover velocity after a child's fling animation completes. If the child is still flinging, it returns Velocity.Zero; otherwise, it executes the remaining fling animation via doFlingAnimation.
• FlingCancellationException: An internal exception thrown when a fling hits the bounds of a node or the node leaves composition, allowing the leftover velocity to be passed to a nested scroll node above.

/** Opens a scrolling session with nested scrolling and overscroll support. */
suspend fun scroll(
    scrollPriority: MutatePriority = MutatePriority.Default,
    block: suspend NestedScrollScope.() -> Unit,
) {
    scrollableState.scroll(scrollPriority) {
        outerStateScope = this
        block.invoke(nestedScrollScope)
    }
}

Use the Stateless + Wrapper pattern to create highly reusable and testable UI components.

1. Stateless Composable: Accepts raw values and callbacks (e.g., onToggle: (Boolean) -> Unit). It does not manage its own state. This makes it easy to test and reuse in different contexts.
2. Stateful Wrapper: Manages the state internally using remember and calls the stateless child. This provides a convenient API for simple, isolated use cases.

Advantage: The caller can choose to manage the state themselves (using the stateless version) or use the convenience wrapper (the stateful version).

// Stateless: Reusable and testable
@Composable
fun ToggleButton(
    isEnabled: Boolean,
    onToggle: (Boolean) -> Unit,
    text: String
) { ... }

// Stateful: Manages its own state
@Composable
fun StatefulToggleButton(text: String = "Toggle") {
    var isEnabled by remember { mutableStateOf(false) }
    ToggleButton(isEnabled, { isEnabled = it }, text)
}