kmp-navigation

Files (1)

• SKILL.md

SKILL.md (first lines)

# KMP Navigation

> The kmptv template uses state-based navigation (not Jetpack Navigation Compose). This is intentional — Navigation Compose has known focus-restoration issues on TV that make it unreliable for D-pad apps.

## Navigation model

The Android TV app manages navigation via state variables in `MainScreen()`:

```kotlin
@Composable
private fun MainScreen() {
    var selectedItem by remember { mutableStateOf<ContentItem?>(null) }
    var showingDetail by rememberSaveable { mutableStateOf(false) }
    var showingVideoPlayer by rememberSaveable { mutableStateOf(false) }

    BackHandler(enabled = showingVideoPlayer || showingDetail) {
        if (showingVideoPlayer) {
            showingVideoPlayer = false
        } else if (showingDetail) {
            showingDetail = false
            selectedItem = null
        }
    }

    when {
        showingVideoPlayer && selectedItem?.videoUrl != null ->
            VideoPlayerScreen(item = selectedItem!!, onBack = { showingVideoPlayer = false })
        showingDetail && selectedItem != null ->
            ContentDetailScreen(item = selectedItem!!, onBack = { showingDetail = false })
        else ->
            HomeScreen(onItemClick = { item ->
                selectedItem = item
                showingDetail = true
            })
    }
}
```

### Why state-based, not NavHost

1. **Focus restoration:** NavHost loses focus position when popping the back stack. TV users expect to return to the exact card they left.
2. **Simplicity:** Three screens with boolean flags is easier to reason about than a NavGraph with arguments.
3. **Animation control:** `Crossfade` and custom transitions work naturally with `when` blocks.
4. **rememberSaveable:** Screen state survives configuration changes without NavGraph SavedState complexity.

## BackHandler — back stack behavior

```kotlin
import androidx.activity.compose.BackHandler

BackHandler(enabled = /* when this screen is active */) {
    // Pop this screen
}
```

**Rules:**
- Always provide `enabled` parameter scoped to the current screen. Without it, back handling fires when it shouldn't.
- Priority: innermost enabled BackHandler wins. So the player's BackHandler fires before the detail's.
- On the home screen, don't add a BackHandler — let the system handle app exit.

### Back stack ordering

```
Home (no BackHandler — system exits app)
  └── Detail (BackHandler → goes back to Home)
       └── VideoPlayer (BackHandler → goes back to Detail)
```

## Adding a new screen

1. **Create the composable** in `androidtv-app/src/main/java/.../compose/`:

```kotlin
@Composable
fun NewScreen(
    item: ContentItem,
    onBack: () -> Unit,
) {
    // Screen content
}
```

2. **Add state variable** in MainScreen:

```kotlin
var showingNewScreen by rememberSaveable { mutableStateOf(false) }
```

3. **Add to the `when` block** (order matters — more specific screens first):

```kotlin
when {
    showingVideoPlayer -> VideoPlayerScreen(...)
    showingNewScreen -> NewScreen(item = selectedItem!!, onBack = { showingNewScreen = false })
    showingDetail -> ContentDetailScreen(...)
    else -> HomeScreen(...)
}
```

4. **Add BackHandler** entry:

```kotlin
BackHandler(enabled = showingNewScreen) {
    showingNewScreen = false
}
```

## Screen transitions

The template uses `Crossfade` for the hero banner. For screen transitions, the `when` block provides an instant swap. To add animated transitions:

```kotlin
AnimatedContent(
    targetState = currentScreen,
    transitionSpec = {
        fadeIn(tween(300)) togetherWith fadeOut(tween(300))
    }
) { screen ->
    when (screen) {

From giolaq/tv-build-harness, MIT-0.

More from giolaq/tv-build-harness