# Settings Focus Containment — D-pad Flow Within a Parent Sidebar

## Problem

When a settings screen has its own internal rail (left sidebar with settings categories) and lives inside a parent Netflix-style sidebar, the internal rail must be navigable with UP/DOWN while LEFT from content opens the parent sidebar.

## Common Anti-Pattern (DO NOT USE)

**DO NOT** add an `onPreviewKeyEvent` that eats UP/DOWN/LEFT events when the rail has focus:

```kotlin
// BROKEN — blocks UP/DOWN navigation, user literally cannot move through the menu:
.onPreviewKeyEvent { event ->
    if (event.type == KeyEventType.KeyDown) {
        when (event.key) {
            Key.DirectionLeft, Key.DirectionDown, Key.DirectionUp -> !allowDetailFocus
            else -> false
        }
    } else false
}
```

This was the #1 cause of "settings navigation broken" on Android TV. Eating `Key.DirectionUp` and `Key.DirectionDown` prevents the user from moving between rail items. The LazyColumn can't scroll because the events never reach its children.

## Correct Approach: Let D-pad Flow Naturally

The parent sidebar should be a simple `Row` layout with sidebar `Column` + content `Box` — NO key event interception on the content area itself:

```kotlin
// NetflixSideNavigation — correct layout:
Row(modifier = Modifier.fillMaxSize()) {
    // Sidebar rail (left side, has its own focusable nav items)
    Column(Modifier.width(actualWidth).fillMaxHeight()) {
        NAV_ITEMS.forEach { item ->
            NetflixNavItem(item, onFocus = { isExpanded = true }, onClick = { navigate() })
        }
    }
    // Content area — NO key interception, just renders the screen
    Box(Modifier.weight(1f).fillMaxHeight()) {
        content()
    }
}
```

**Why this works:**
1. Sidebar is always on the left with its own focusable items
2. Content area is a plain `Box` — no `onKeyEvent`, no `onPreviewKeyEvent`
3. Pressing LEFT from a content focusable moves focus to the nearest item to the left — the sidebar
4. Pressing RIGHT from the sidebar moves focus to content — Compose D-pad handles this naturally
5. UP/DOWN within settings rail work because nothing intercepts them
6. This IS the Netflix behavior — LEFT opens sidebar, RIGHT closes it

**Settings screen internal navigation:**
```kotlin
Box(Modifier.fillMaxSize()) {  // NO key event interception!
    Row {
        // Settings rail (LazyColumn of SettingsRailButton items)
        Column(Modifier.width(railWidth)) {
            LazyColumn {
                items(panels) { panel ->
                    SettingsRailButton(
                        onNavigateRight = { /* transfer focus to detail pane */ }
                    )
                }
            }
        }
        // Detail pane — onKeyEvent for LEFT to move back to rail:
        Box(Modifier.onKeyEvent { event ->
            if (event.key == Key.DirectionLeft) {
                focusManager.moveFocus(FocusDirection.Left); true
            } else false
        }) { /* detail content */ }
    }
}
```

## Key Rules

1. **Parent sidebar content Box**: NO key event interception. Render plain `Box { content() }`.
2. **Settings outer Box**: NO `onPreviewKeyEvent` eating UP/DOWN/LEFT. Just `Box(Modifier.fillMaxSize())`.
3. **Detail pane**: `onKeyEvent` for LEFT → move focus back to rail. This is targeted, not broad.
4. **Rail items**: `onPreviewKeyEvent` for RIGHT → move focus to detail pane. Optional chevron hint.
5. **Sidebar nav items**: `onPreviewKeyEvent` for RIGHT → collapse sidebar + focus content.

## When the Parent Sidebar Still Has Focus Issues

If the sidebar was previously using HazeState, `focusGroup()`, `BackHandler`, or complex pending-state booleans — rewrite it to the simple Row layout. See `references/android-tv-sidebar-simplification.md` for the full rewrite pattern.

## Related Patterns

- `android-project-build` Trap 39: D-pad focus TV triple requirement
- `references/android-tv-sidebar-simplification.md`: Netflix sidebar rewrite pattern