Skip to content

po4yka/RIPDPI / .agents/skills/compose

compose

Verified

Jetpack Compose API guidance (state, modifiers, navigation, theming) plus a scored RIPDPI audit. Use for generic Compose API questions or an audit. Not for RIPDPI conventions (see android-compose-patterns).

references/state-holder-vs-viewmodel.md

View on GitHub
# Compose state-holder / UI split

## Core principle

Separate state-holder wiring from UI rendering. The state-holder composable talks to ViewModels, components, flows, navigation, and side effects. The UI composable takes plain immutable UI state plus callbacks and describes layout.

This keeps screens previewable, testable, and easier to reuse across surfaces.

## When to apply

Use this when a Compose screen:

- Takes a ViewModel, component, controller, navigator, repository, or service directly.
- Collects app/business state or side effects in the same function that lays out most UI.
- Passes a whole state holder into child composables instead of explicit state and callbacks.
- Is hard to preview because it needs dependency injection, navigation, lifecycle, or fake services.
- Has UI tests that must construct a full app stack to verify a simple layout branch.

## The pattern

Use a small public state-holder composable:

```kotlin
@Composable
fun ProfileScreen(viewModel: ProfileViewModel, modifier: Modifier = Modifier) {
    val state by viewModel.uiState.collectAsStateWithLifecycle()

    ProfileScreen(
        state = state,
        onNameChange = viewModel::onNameChange,
        onSaveClick = viewModel::save,
        onBackClick = viewModel::back,
        modifier = modifier,
    )
}
```

Then put UI in a plain composable that knows nothing about the state holder:

```kotlin
@Composable
fun ProfileScreen(
    state: ProfileUiState,
    onNameChange: (String) -> Unit,
    onSaveClick: () -> Unit,
    onBackClick: () -> Unit,
    modifier: Modifier = Modifier,
) {
    ProfileContent(
        name = state.name,
        isSaving = state.isSaving,
        canSave = state.canSave,
        onNameChange = onNameChange,
        onSaveClick = onSaveClick,
        onBackClick = onBackClick,
        modifier = modifier,
    )
}
```

Private content functions can break up layout:

```kotlin
@Composable
private fun ProfileContent(
    name: String,
    isSaving: Boolean,
    canSave: Boolean,
    onNameChange: (String) -> Unit,
    onSaveClick: () -> Unit,
    onBackClick: () -> Unit,
    modifier: Modifier = Modifier,
) {
    // Layout only.
}
```

## Rules of thumb

| Concern | State-holder composable | UI composable |
|---|---|---|
| Collect ViewModel/component state | Yes | No |
| Collect one-shot effects | Yes, or a tiny sibling effect handler | Usually no |
| Hold dependency-injected objects | Yes | No |
| Accept immutable UI state | Usually passes it through | Yes |
| Accept lambdas for user events | Wires them | Calls them |
| Own layout, modifiers, semantics, test tags | No/minimal | Yes |
| Own UI-local state like scroll, focus, text input, animation, interaction | Sometimes seeds it | Yes |
| Preview/screenshot friendly | Not necessarily | Yes |

The "no collection in UI composables" rule is about app/business state and side-effect streams. Plain UI composables can still own UI-local framework state: `rememberScrollState`, `rememberLazyListState`, `FocusRequester`, focus state, animation state, `TextFieldState`, `MutableInteractionSource.collectIsPressedAsState()`, and similar behavior that belongs to the rendered widget.

If that UI-local state grows into coordinated behavior with multiple related fields and operations, use `references/state-hoisting.md` to decide whether it should become a plain state holder class remembered in composition.

## What to pass

Pass the smallest useful UI contract:

- Prefer a dedicated `UiState`/`State` object over many unrelated primitives when the screen has real state.
- Prefer explicit lambdas (`onRetryClick`, `onItemSelected`) over passing a whole ViewModel/component.
- Keep domain models out of the UI composable if they force business rules into UI. Map to UI models when the UI needs a different shape.
- Keep navigation as callbacks. The UI composable says "user clicked back", not "navigate to route X".
- Frame-rate or UI-local values that should not force whole-tree recomposition when they change: prefer provider lambdas and deferred reads per `references/deferred-reads.md`.

## Side effects

`references/side-effects.md` covers effect APIs (`LaunchedEffect`, `DisposableEffect`, `SideEffect`), keys, cleanup, and `rememberUpdatedState`.

Handle effects near the state holder, where the effect source and imperative target are both available:

```kotlin
@Composable
fun ProfileScreen(viewModel: ProfileViewModel, snackbarHostState: SnackbarHostState) {
    val state by viewModel.uiState.collectAsStateWithLifecycle()

    LaunchedEffect(viewModel) {
        viewModel.effects.collect { effect ->
            when (effect) {
                ProfileEffect.Saved -> snackbarHostState.showSnackbar("Saved")
            }
        }
    }

    ProfileScreen(state = state, onSaveClick = viewModel::save)
}
```

If effect handling grows, extract `ProfileEffects(viewModel, snackbarHostState)` rather than pushing the ViewModel into the UI composable.

## Common mistakes

| Mistake | Why it hurts | Fix |
|---|---|---|
| `fun Screen(viewModel: MyViewModel)` contains all layout | Hard to preview/test without Android lifecycle and DI | Add a plain UI overload that takes `state` and callbacks |
| Child composables take `viewModel`/`component` | Dependencies leak through the tree | Pass only the state/callbacks that child needs |
| UI composable launches navigation | UI becomes coupled to app routing | Expose `onBackClick`, `onItemClick`, etc. |
| UI composable collects app/business flows | Collection lifecycle is hidden in layout | Collect near the state holder and pass values down |
| UI-local state is hoisted into the state holder for no reason | State holder starts owning layout mechanics | Keep scroll/focus/animation/text-field interaction state in the UI composable when it is only UI behavior |
| Every tiny composable gets a state-holder overload | Too much ceremony | Split at screen/section boundaries, not every `Row` |

## When NOT to apply

- Tiny one-off composables that already take plain values and callbacks.
- Design-system primitives such as `Button`, `Card`, or `ListItem`; those should expose slots and modifiers, not state holders.
- Cases where the state-holder composable would only forward one primitive and add no isolation.

## Related

- `references/state-hoisting.md` — deciding where UI element state and UI logic should live, including plain state holder classes.
- `references/deferred-reads.md` — provider lambdas for frame-rate values that cross composable boundaries.
- `references/side-effects.md` — choosing effect APIs and where to wire them.
rea-analysis-optimizationmorluto/reaOptimize REA providers and shared analysis workflows for agent context, latency, CPU, and memory while preserving correctness and Evidence. Use for analysis bottlenecks and cache or query design; CI/test-suite optimization belongs to rea-ci-tests-audit.Stars: 471kUpdated Claude CodeCodexVerifiedInstall
rea-ci-tests-auditmorluto/reaAudit REA CI and test suites for correctness, fixture drift, false passes, and measured performance; use for suite or workflow investigations and efficiency changes, rather than ordinary feature testing or a single test failure.Stars: 471kUpdated Claude CodeCodexVerifiedInstall
rea-tool-designmorluto/reaAudit, investigate, design, or change REA investigation tools, CLI/MCP contracts, provider capabilities, and Evidence semantics.Stars: 471kUpdated Claude CodeCodexVerifiedInstall
ponytail-auditDietrichGebert/ponytailQuality audit of the whole repo: bugs, security, real load, missing tests, speed, and what to delete. Most important first.Stars: 194kUpdated Claude CodeCodexVerifiedInstall