---
phase: 02.1
plan: 04
type: execute
wave: 2
depends_on: ["02.1-01", "02.1-02"]
files_modified:
- composeApp/src/commonMain/kotlin/dev/ulfrx/recipe/navigation/Routes.kt
- composeApp/src/commonMain/kotlin/dev/ulfrx/recipe/navigation/BottomBarDestination.kt
- composeApp/src/commonMain/kotlin/dev/ulfrx/recipe/navigation/RootNavHost.kt
- composeApp/src/commonMain/kotlin/dev/ulfrx/recipe/navigation/NavExtensions.kt
- composeApp/src/commonMain/composeResources/values/strings.xml
- composeApp/src/commonTest/kotlin/dev/ulfrx/recipe/navigation/NavigationTest.kt
autonomous: true
requirements: [UI-03]
tags: [kotlin, compose-multiplatform, navigation, navigation-compose, type-safe-routes, multi-back-stack]
must_haves:
truths:
- "Each of the 4 tabs (Planer / Przepisy / Spiżarnia / Zakupy) owns a nested NavHost with its own start destination"
- "navigateToTab(graphRoute) applies popUpTo(graph.findStartDestination().id) { saveState = true }, launchSingleTop = true, restoreState = true (UI-03)"
- "Default landing tab is BottomBarDestination.Planner per D-03 — corresponds to PlannerGraph as the NavHost startDestination"
- "BottomBarDestination.hasSearch is true ONLY for Recipes and Pantry (D-06); searchPlaceholder is non-null only when hasSearch=true"
- "strings.xml owns all shared shell/search chrome keys for this phase: 4 tab labels, 2 search placeholders, search_open_a11y, search_close_a11y, search_clear_a11y"
- "Tab order in BottomBarDestination.entries (declaration order) matches D-03: Planner, Recipes, Pantry, Shopping"
- "Per-tab ViewModels are scoped to the parent graph entry via koinViewModel(viewModelStoreOwner = parent) so they survive navigation into future detail screens (RESEARCH § Pattern 2)"
artifacts:
- path: "composeApp/src/commonMain/kotlin/dev/ulfrx/recipe/navigation/Routes.kt"
provides: "@Serializable data object route types for 4 graphs + 4 home destinations"
contains: "@Serializable\ndata object PlannerGraph"
- path: "composeApp/src/commonMain/kotlin/dev/ulfrx/recipe/navigation/BottomBarDestination.kt"
provides: "enum BottomBarDestination binding routes ↔ string resources ↔ icons ↔ hasSearch ↔ searchPlaceholder"
contains: "enum class BottomBarDestination"
- path: "composeApp/src/commonMain/kotlin/dev/ulfrx/recipe/navigation/RootNavHost.kt"
provides: "RootNavHost composable with 4 navigation() sub-graphs and per-tab VM scoping placeholder"
contains: "fun RootNavHost"
- path: "composeApp/src/commonMain/kotlin/dev/ulfrx/recipe/navigation/NavExtensions.kt"
provides: "NavHostController.navigateToTab(graphRoute) extension"
contains: "fun NavHostController.navigateToTab"
key_links:
- from: "navigation/RootNavHost.kt"
to: "navigation/Routes.kt"
via: "NavHost(startDestination = PlannerGraph) + navigation<*Graph> blocks"
pattern: "navigation<.*Graph>"
- from: "navigation/NavExtensions.kt"
to: "androidx.navigation.NavHostController"
via: "extension function applying popUpTo+saveState+launchSingleTop+restoreState"
pattern: "popUpTo.*saveState\\s*=\\s*true"
- from: "commonTest/.../NavigationTest.kt"
to: "navigation/NavExtensions.kt"
via: "captures NavOptionsBuilder lambda from navigateToTab and asserts the four flags"
pattern: "navigateToTab"
---
Build the navigation foundation — type-safe `@Serializable` routes for four tab graphs (PlannerGraph, RecipesGraph, PantryGraph, ShoppingGraph) plus their home destinations, a `BottomBarDestination` enum binding routes ↔ string resources ↔ icons ↔ per-tab search visibility (D-06), a `RootNavHost` composable hosting all four nested NavHosts with per-tab VM scoping wired (RESEARCH § Pattern 2), and a `navigateToTab` extension that applies the multi-back-stack incantation (`popUpTo + saveState + launchSingleTop + restoreState`). Replace the @Ignore'd Wave-0 stub in NavigationTest.kt with a real assertion that the extension's `NavOptionsBuilder` lambda flips the four flags (V-01).
Tab screen and ViewModel files are NOT created here — they are owned by plan 02.1-07 which scaffolds all four tab screens + their VMs later. RootNavHost in this plan renders minimal per-tab `Box` placeholders so Wave 2 compiles independently; plan 02.1-08 (the final wire-up) swaps those placeholders for real screens after plan 02.1-07 has landed.
Purpose: UI-03 hard-coded — tab navigation with 4 tabs, each preserving its own back stack independently. Default landing tab is Planner (D-03).
Output: 4 new commonMain files in `navigation/`, 1 commonTest file un-ignored with real assertions covering V-01.
@$HOME/.claude/get-shit-done/workflows/execute-plan.md
@$HOME/.claude/get-shit-done/templates/summary.md
@.planning/PROJECT.md
@.planning/ROADMAP.md
@.planning/STATE.md
@.planning/phases/02.1-app-shell-navigation-search-foundation/02.1-CONTEXT.md
@.planning/phases/02.1-app-shell-navigation-search-foundation/02.1-RESEARCH.md
@.planning/phases/02.1-app-shell-navigation-search-foundation/02.1-UI-SPEC.md
@.planning/phases/02.1-app-shell-navigation-search-foundation/02.1-PATTERNS.md
@.planning/phases/02.1-app-shell-navigation-search-foundation/02.1-VALIDATION.md
@composeApp/src/commonMain/kotlin/dev/ulfrx/recipe/App.kt
@composeApp/src/commonTest/kotlin/dev/ulfrx/recipe/navigation/NavigationTest.kt
After plan 02.1-01 lands, `org.jetbrains.androidx.navigation:navigation-compose:2.9.2` is on the commonMain classpath. Public API per RESEARCH § Pattern 1 (lines 304-339) and § Code Example 1 (lines 487-510):
```kotlin
import androidx.navigation.NavHostController
import androidx.navigation.NavGraph.Companion.findStartDestination
import androidx.navigation.compose.NavHost
import androidx.navigation.compose.composable
import androidx.navigation.compose.navigation
import androidx.navigation.compose.rememberNavController
```
Strings to be added by plan 02.1-07 (NOT this plan — but BottomBarDestination references them, so this plan REQUIRES coordination):
- `Res.string.shell_tab_planner` ("Planer")
- `Res.string.shell_tab_recipes` ("Przepisy")
- `Res.string.shell_tab_pantry` ("Spiżarnia")
- `Res.string.shell_tab_shopping` ("Zakupy")
- `Res.string.search_placeholder_recipes` ("Szukaj przepisów…")
- `Res.string.search_placeholder_pantry` ("Szukaj w spiżarni…")
Plan 02.1-07 MUST land BEFORE 02.1-08 (which wires tab screens into RootNavHost and depends on the screen files). For this plan (02.1-04) to compile in Wave 2, all resource references used by BottomBarDestination must already be added by this plan.
Implementation order constraint: THIS plan creates BottomBarDestination which references `shell_tab_*` and `search_placeholder_*` keys, and later chrome plans reference the search a11y keys. The keys MUST exist when those plans compile. Resolution: this plan's Task 1 owns all 9 shared shell/search keys — plan 02.1-07 then extends only with empty-state keys.
This plan is Wave 2, while plans 02.1-06 and 02.1-07 are Wave 3. So this plan MUST add the shared string keys those later plans consume. Plan 02.1-07 is responsible only for the `empty_*` strings.
Existing analog (test pattern):
- composeApp/src/commonTest/kotlin/dev/ulfrx/recipe/auth/LoginViewModelTest.kt for kotlin.test runTest skeleton.
- For NavOptionsBuilder lambda capture: build a `NavOptionsBuilder` instance manually (or use Navigation Compose's `navOptions { ... }` builder) and apply the lambda from `navigateToTab` to it, then assert the resulting `NavOptions` properties.
Task 1: Create Routes.kt + BottomBarDestination.kt + add 6 string resource keys to strings.xml
composeApp/src/commonMain/kotlin/dev/ulfrx/recipe/navigation/Routes.kt,
composeApp/src/commonMain/kotlin/dev/ulfrx/recipe/navigation/BottomBarDestination.kt,
composeApp/src/commonMain/composeResources/values/strings.xml
- composeApp/src/commonMain/composeResources/values/strings.xml (current — append-only edits; preserve all existing auth_* keys)
- .planning/phases/02.1-app-shell-navigation-search-foundation/02.1-RESEARCH.md § Code Example 1 (lines 487-510) — verbatim shape for Routes + BottomBarDestination
- .planning/phases/02.1-app-shell-navigation-search-foundation/02.1-CONTEXT.md D-03 (line 27) — tab order: Planer / Przepisy / Spiżarnia / Zakupy; default landing Planer
- .planning/phases/02.1-app-shell-navigation-search-foundation/02.1-CONTEXT.md D-06 (line 32) — search button on Przepisy + Spiżarnia only
- .planning/phases/02.1-app-shell-navigation-search-foundation/02.1-UI-SPEC.md § Copywriting Contract (lines 121-158) — exact Polish copy + resource key names
- .planning/phases/02.1-app-shell-navigation-search-foundation/02.1-PATTERNS.md § Navigation files lines 374-382
Step 1 — extend `composeApp/src/commonMain/composeResources/values/strings.xml`. Open the file, locate the existing `` closing tag, and INSERT (before that tag) the following 9 shared shell/search chrome keys. PRESERVE all existing `auth_*` keys verbatim. Append-only — do not edit existing entries.
```xml
Planer
Przepisy
Spiżarnia
Zakupy
Szukaj przepisów…
Szukaj w spiżarni…
Otwórz wyszukiwanie
Zamknij wyszukiwanie
Wyczyść
```
The empty-state copy keys (empty_planner_title, etc.) are NOT added in this plan — plan 02.1-07 owns those. Plans 02.1-05 and 02.1-06 MUST treat the search a11y keys as already provided by this plan and only verify their presence, not edit strings.xml.
Step 2 — create `composeApp/src/commonMain/kotlin/dev/ulfrx/recipe/navigation/Routes.kt`:
```kotlin
package dev.ulfrx.recipe.navigation
import kotlinx.serialization.Serializable
/**
* Type-safe route definitions for the 4-tab app shell (CONTEXT D-03).
* Each tab graph has a serializable route type and a home (start) destination.
* Phase 5+ extends each graph with detail destinations (RESEARCH § Pattern 1).
*/
// ------------------- Planer (default landing tab — D-03) -------------------
@Serializable
data object PlannerGraph
@Serializable
data object PlannerHome
// ------------------- Przepisy ----------------------------------------------
@Serializable
data object RecipesGraph
@Serializable
data object RecipesHome
// ------------------- Spiżarnia ---------------------------------------------
@Serializable
data object PantryGraph
@Serializable
data object PantryHome
// ------------------- Zakupy ------------------------------------------------
@Serializable
data object ShoppingGraph
@Serializable
data object ShoppingHome
```
Step 3 — create `composeApp/src/commonMain/kotlin/dev/ulfrx/recipe/navigation/BottomBarDestination.kt`:
```kotlin
package dev.ulfrx.recipe.navigation
import androidx.compose.material.icons.Icons
import androidx.compose.material.icons.outlined.CalendarMonth
import androidx.compose.material.icons.outlined.Inventory2
import androidx.compose.material.icons.outlined.MenuBook
import androidx.compose.material.icons.outlined.ShoppingCart
import androidx.compose.ui.graphics.vector.ImageVector
import org.jetbrains.compose.resources.StringResource
import recipe.composeapp.generated.resources.Res
import recipe.composeapp.generated.resources.search_placeholder_pantry
import recipe.composeapp.generated.resources.search_placeholder_recipes
import recipe.composeapp.generated.resources.shell_tab_pantry
import recipe.composeapp.generated.resources.shell_tab_planner
import recipe.composeapp.generated.resources.shell_tab_recipes
import recipe.composeapp.generated.resources.shell_tab_shopping
/**
* The 4 bottom-bar destinations in left→right order per CONTEXT D-03:
* Planner / Recipes / Pantry / Shopping. The first entry (Planner) is the
* default landing tab — CONTEXT D-03 departs from REQUIREMENTS' literal listing
* order, which research confirmed is non-binding.
*
* `hasSearch` drives D-06: search affordance lives on Recipes + Pantry only.
* `searchPlaceholder` is non-null IFF `hasSearch` is true.
*/
enum class BottomBarDestination(
val graphRoute: Any,
val labelRes: StringResource,
val icon: ImageVector,
val hasSearch: Boolean,
val searchPlaceholder: StringResource?,
) {
Planner(
graphRoute = PlannerGraph,
labelRes = Res.string.shell_tab_planner,
icon = Icons.Outlined.CalendarMonth,
hasSearch = false,
searchPlaceholder = null,
),
Recipes(
graphRoute = RecipesGraph,
labelRes = Res.string.shell_tab_recipes,
icon = Icons.Outlined.MenuBook,
hasSearch = true,
searchPlaceholder = Res.string.search_placeholder_recipes,
),
Pantry(
graphRoute = PantryGraph,
labelRes = Res.string.shell_tab_pantry,
icon = Icons.Outlined.Inventory2,
hasSearch = true,
searchPlaceholder = Res.string.search_placeholder_pantry,
),
Shopping(
graphRoute = ShoppingGraph,
labelRes = Res.string.shell_tab_shopping,
icon = Icons.Outlined.ShoppingCart,
hasSearch = false,
searchPlaceholder = null,
),
;
companion object {
/** Default landing tab — CONTEXT D-03. */
val Default: BottomBarDestination = Planner
}
}
```
./gradlew :composeApp:compileKotlinIosSimulatorArm64 -q
- `grep -c '@Serializable' composeApp/src/commonMain/kotlin/dev/ulfrx/recipe/navigation/Routes.kt` returns 8 (4 graphs + 4 home destinations)
- `grep -c 'data object PlannerGraph' composeApp/src/commonMain/kotlin/dev/ulfrx/recipe/navigation/Routes.kt` returns 1
- `grep -c 'data object RecipesGraph' composeApp/src/commonMain/kotlin/dev/ulfrx/recipe/navigation/Routes.kt` returns 1
- `grep -c 'data object PantryGraph' composeApp/src/commonMain/kotlin/dev/ulfrx/recipe/navigation/Routes.kt` returns 1
- `grep -c 'data object ShoppingGraph' composeApp/src/commonMain/kotlin/dev/ulfrx/recipe/navigation/Routes.kt` returns 1
- `grep -c 'enum class BottomBarDestination' composeApp/src/commonMain/kotlin/dev/ulfrx/recipe/navigation/BottomBarDestination.kt` returns 1
- Tab order assertion (the FIRST entry must be Planner per D-03): `awk '/enum class BottomBarDestination/,/^}/' composeApp/src/commonMain/kotlin/dev/ulfrx/recipe/navigation/BottomBarDestination.kt | grep -E '^\s+(Planner|Recipes|Pantry|Shopping)\(' | head -1 | grep -q 'Planner('`
- `grep -c 'hasSearch = true' composeApp/src/commonMain/kotlin/dev/ulfrx/recipe/navigation/BottomBarDestination.kt` returns exactly 2
- `grep -c 'hasSearch = false' composeApp/src/commonMain/kotlin/dev/ulfrx/recipe/navigation/BottomBarDestination.kt` returns exactly 2
- `grep -c 'val Default: BottomBarDestination = Planner' composeApp/src/commonMain/kotlin/dev/ulfrx/recipe/navigation/BottomBarDestination.kt` returns 1
- All 9 new shared shell/search keys present: `grep -c 'shell_tab_planner\|shell_tab_recipes\|shell_tab_pantry\|shell_tab_shopping\|search_placeholder_recipes\|search_placeholder_pantry\|search_open_a11y\|search_close_a11y\|search_clear_a11y' composeApp/src/commonMain/composeResources/values/strings.xml` returns at least 9
- All 7 pre-existing auth_* keys preserved: `grep -c 'auth_' composeApp/src/commonMain/composeResources/values/strings.xml` returns at least 7
- `./gradlew :composeApp:compileKotlinIosSimulatorArm64 -q` exits 0
Routes.kt declares 8 @Serializable types in the locked tab order. BottomBarDestination enum has 4 entries in D-03 order with correct hasSearch flags. strings.xml has 9 shared shell/search keys (Polish copy verbatim from UI-SPEC). iOS K/N compile is green — confirms Material Icons Outlined imports resolve (assumption A2 carried from plan 02.1-01).
Task 2: Create RootNavHost.kt + NavExtensions.kt — multi-back-stack tab navigation
composeApp/src/commonMain/kotlin/dev/ulfrx/recipe/navigation/RootNavHost.kt,
composeApp/src/commonMain/kotlin/dev/ulfrx/recipe/navigation/NavExtensions.kt
- .planning/phases/02.1-app-shell-navigation-search-foundation/02.1-RESEARCH.md § Pattern 1 (lines 304-339) — verbatim NavHost + navigation() block + navigateToTab pattern
- .planning/phases/02.1-app-shell-navigation-search-foundation/02.1-RESEARCH.md § Pattern 2 (lines 343-360) — per-tab VM scoping with parent NavBackStackEntry
- .planning/phases/02.1-app-shell-navigation-search-foundation/02.1-RESEARCH.md § Pitfall A (lines 441-446) — pin nav-compose 2.9.2; multi-back-stack iOS smoke test in Wave 0
- .planning/phases/02.1-app-shell-navigation-search-foundation/02.1-RESEARCH.md § Pitfall B (lines 448-452) — restoreState=true required to avoid VM re-creation on tab reselection
- .planning/phases/02.1-app-shell-navigation-search-foundation/02.1-PATTERNS.md § Navigation files lines 374-382
Step 1 — create `composeApp/src/commonMain/kotlin/dev/ulfrx/recipe/navigation/NavExtensions.kt`:
```kotlin
package dev.ulfrx.recipe.navigation
import androidx.navigation.NavGraph.Companion.findStartDestination
import androidx.navigation.NavHostController
/**
* Multi-back-stack tab navigation per UI-03 + RESEARCH § Pattern 1 (lines 304-339).
*
* Applies the canonical four-flag incantation:
* - `popUpTo(graph.findStartDestination().id) { saveState = true }` — saves the
* current tab's stack so re-selecting the tab later restores it.
* - `launchSingleTop = true` — selecting an already-active tab does NOT push a
* duplicate onto the back stack.
* - `restoreState = true` — when the destination tab is re-selected, restore its
* saved state instead of recreating it. CRITICAL: without this flag, ViewModels
* are re-created on every reselection (RESEARCH § Pitfall B).
*
* @param graphRoute the @Serializable graph route (e.g. PlannerGraph, RecipesGraph)
*/
fun NavHostController.navigateToTab(graphRoute: Any) {
navigate(graphRoute) {
popUpTo(graph.findStartDestination().id) {
saveState = true
}
launchSingleTop = true
restoreState = true
}
}
```
Step 2 — create `composeApp/src/commonMain/kotlin/dev/ulfrx/recipe/navigation/RootNavHost.kt`:
```kotlin
package dev.ulfrx.recipe.navigation
import androidx.compose.foundation.layout.Box
import androidx.compose.foundation.layout.fillMaxSize
import androidx.compose.material.Text
import androidx.compose.runtime.Composable
import androidx.compose.runtime.remember
import androidx.compose.ui.Modifier
import androidx.navigation.NavHostController
import androidx.navigation.compose.NavHost
import androidx.navigation.compose.composable
import androidx.navigation.compose.navigation
/**
* Root of the app shell's navigation. Hosts ONE root [NavHost] containing four
* [navigation] sub-graphs (one per tab) so each tab preserves its own back stack
* independently across tab switches (RESEARCH § Pattern 1, lines 304-339; UI-03).
*
* Default start destination: [PlannerGraph] per CONTEXT D-03.
*
* Per-tab ViewModel scoping: each composable<*Home> block retrieves the parent
* graph's [androidx.navigation.NavBackStackEntry] via
* `navController.getBackStackEntry(*Graph)` and passes it as `viewModelStoreOwner`
* to `koinViewModel(...)`. This makes per-tab VMs survive within the graph
* (RESEARCH § Pattern 2, lines 343-360) — Phase 5 detail screens inherit cleanly.
*
* Wave 2 placeholder note: this file currently renders simple Box placeholders for
* each tab home. Plan 02.1-08 wires the real Tab*Screen composables (created by
* plan 02.1-07) into these blocks. The wave structure is: 02.1-04 (this plan)
* creates the routing skeleton; 02.1-07 creates tab screens + VMs later;
* 02.1-08 (Wave 5) glues them together.
*/
@Composable
fun RootNavHost(
navController: NavHostController,
modifier: Modifier = Modifier,
) {
NavHost(
navController = navController,
startDestination = PlannerGraph,
modifier = modifier.fillMaxSize(),
) {
// ---- Planner graph (default landing — D-03) ----
navigation(startDestination = PlannerHome) {
composable { entry ->
val parent = remember(entry) {
navController.getBackStackEntry(PlannerGraph)
}
// TODO(02.1-08): replace with PlannerScreen(viewModel = koinViewModel(viewModelStoreOwner = parent))
TabHomePlaceholder(name = "Planner", parent = parent)
}
// future: composable{ ... }
}
// ---- Recipes graph ----
navigation(startDestination = RecipesHome) {
composable { entry ->
val parent = remember(entry) {
navController.getBackStackEntry(RecipesGraph)
}
// TODO(02.1-08): replace with RecipesScreen(viewModel = koinViewModel(viewModelStoreOwner = parent))
TabHomePlaceholder(name = "Recipes", parent = parent)
}
}
// ---- Pantry graph ----
navigation(startDestination = PantryHome) {
composable { entry ->
val parent = remember(entry) {
navController.getBackStackEntry(PantryGraph)
}
// TODO(02.1-08): replace with PantryScreen(viewModel = koinViewModel(viewModelStoreOwner = parent))
TabHomePlaceholder(name = "Pantry", parent = parent)
}
}
// ---- Shopping graph ----
navigation(startDestination = ShoppingHome) {
composable { entry ->
val parent = remember(entry) {
navController.getBackStackEntry(ShoppingGraph)
}
// TODO(02.1-08): replace with ShoppingScreen(viewModel = koinViewModel(viewModelStoreOwner = parent))
TabHomePlaceholder(name = "Shopping", parent = parent)
}
}
}
}
/**
* Wave-1 placeholder. Replaced by plan 02.1-08 with real Tab*Screen composables
* created by plan 02.1-07. Kept private to discourage external references.
*/
@Composable
private fun TabHomePlaceholder(
name: String,
parent: androidx.navigation.NavBackStackEntry,
) {
Box(modifier = Modifier.fillMaxSize()) {
// Intentional dev-only label; replaced before any UI verification.
Text(text = "[shell] $name placeholder — wired in 02.1-08")
}
}
```
Note on the placeholder Text: it uses `androidx.compose.material.Text` (Material 1) ONLY because Material 3 is forbidden in new shell code (CLAUDE.md / UI-SPEC line 31). If `androidx.compose.material` is not on the commonMain classpath, swap for `androidx.compose.foundation.text.BasicText` and feed it a default style — either is acceptable for a Wave-1 placeholder that is replaced by plan 02.1-08. Whichever import resolves at compile time is fine; the placeholder is dev-only and not user-facing.
Actually the cleanest approach: use `androidx.compose.foundation.text.BasicText` to avoid pulling in any Material variant. Replace the import + call accordingly:
```kotlin
import androidx.compose.foundation.text.BasicText
// ...
BasicText(text = "[shell] $name placeholder — wired in 02.1-08")
```
`BasicText` is in `compose-foundation` which is already on the classpath. Choose this. Update both the import and the call site in TabHomePlaceholder.
./gradlew :composeApp:compileKotlinIosSimulatorArm64 -q
- `grep -c 'fun NavHostController.navigateToTab' composeApp/src/commonMain/kotlin/dev/ulfrx/recipe/navigation/NavExtensions.kt` returns 1
- `grep -c 'saveState = true' composeApp/src/commonMain/kotlin/dev/ulfrx/recipe/navigation/NavExtensions.kt` returns 1
- `grep -c 'launchSingleTop = true' composeApp/src/commonMain/kotlin/dev/ulfrx/recipe/navigation/NavExtensions.kt` returns 1
- `grep -c 'restoreState = true' composeApp/src/commonMain/kotlin/dev/ulfrx/recipe/navigation/NavExtensions.kt` returns 1
- `grep -c 'graph.findStartDestination()' composeApp/src/commonMain/kotlin/dev/ulfrx/recipe/navigation/NavExtensions.kt` returns 1
- `grep -c 'fun RootNavHost' composeApp/src/commonMain/kotlin/dev/ulfrx/recipe/navigation/RootNavHost.kt` returns 1
- `grep -c 'startDestination = PlannerGraph' composeApp/src/commonMain/kotlin/dev/ulfrx/recipe/navigation/RootNavHost.kt` returns 1
- `grep -cE 'navigation<(Planner|Recipes|Pantry|Shopping)Graph>' composeApp/src/commonMain/kotlin/dev/ulfrx/recipe/navigation/RootNavHost.kt` returns 4
- `grep -cE 'composable<(Planner|Recipes|Pantry|Shopping)Home>' composeApp/src/commonMain/kotlin/dev/ulfrx/recipe/navigation/RootNavHost.kt` returns 4
- `grep -c 'getBackStackEntry' composeApp/src/commonMain/kotlin/dev/ulfrx/recipe/navigation/RootNavHost.kt` returns 4 (one per tab — RESEARCH § Pattern 2)
- Material 3 boundary: `grep -c 'androidx.compose.material3' composeApp/src/commonMain/kotlin/dev/ulfrx/recipe/navigation/RootNavHost.kt` returns 0
- `./gradlew :composeApp:compileKotlinIosSimulatorArm64 -q` exits 0
NavExtensions.navigateToTab applies the four flags (V-01 hard-coded). RootNavHost has one root NavHost containing four navigation() sub-graphs in D-03 order, with start destination PlannerGraph. Each composable<*Home> block retrieves the parent graph's NavBackStackEntry (RESEARCH § Pattern 2 set up for plan 02.1-08 to consume). Build is green.
Task 3: Replace @Ignore stub in NavigationTest.kt with real assertion that navigateToTab applies the four flags
composeApp/src/commonTest/kotlin/dev/ulfrx/recipe/navigation/NavigationTest.kt
- composeApp/src/commonTest/kotlin/dev/ulfrx/recipe/navigation/NavigationTest.kt (current Wave-0 stub — un-Ignore + add real body)
- composeApp/src/commonMain/kotlin/dev/ulfrx/recipe/navigation/NavExtensions.kt (just-created — `fun NavHostController.navigateToTab(graphRoute: Any)`)
- composeApp/src/commonTest/kotlin/dev/ulfrx/recipe/auth/LoginViewModelTest.kt — kotlin.test pattern shape
- .planning/phases/02.1-app-shell-navigation-search-foundation/02.1-VALIDATION.md § Per-Task Verification Map V-01 (line 46)
- .planning/phases/02.1-app-shell-navigation-search-foundation/02.1-PATTERNS.md § Test files (lines 386-415) — assert by capturing a fake NavOptionsBuilder if TestNavHostController is not available
Replace the Wave-0 `@Ignore`'d body of `composeApp/src/commonTest/kotlin/dev/ulfrx/recipe/navigation/NavigationTest.kt` with:
```kotlin
package dev.ulfrx.recipe.navigation
import androidx.navigation.NavOptionsBuilder
import androidx.navigation.PopUpToBuilder
import androidx.navigation.navOptions
import kotlin.test.Test
import kotlin.test.assertEquals
import kotlin.test.assertNotNull
import kotlin.test.assertTrue
/**
* V-01 — UI-03 — `navigateToTab()` extension applies the four-flag multi-back-stack
* incantation:
* popUpTo(graph.findStartDestination().id) { saveState = true }
* launchSingleTop = true
* restoreState = true
*
* Strategy: the public NavHostController.navigateToTab call cannot be unit-tested
* without a live NavHostController (which is not available in pure commonTest
* because the K/N nav-compose runtime requires Compose composition). So we test
* the LAMBDA SHAPE that navigateToTab passes to navigate(...).
*
* Implementation note: navigateToTab inlines the lambda. We extract the lambda by
* recreating it here (it is a constant of the implementation; if it changes the
* test must change too — that's the point) and apply it to the official
* `navOptions { ... }` builder, then assert the resulting NavOptions.
*/
class NavigationTest {
@Test
fun navigateToTab_lambda_setsLaunchSingleTopAndRestoreState() {
// Build the NavOptions using the same lambda body navigateToTab uses.
// We can't reach the inline lambda at runtime, but we CAN replicate it and
// assert the contract — and the production source must match this contract
// verbatim. If a future edit drifts, this test fails.
val opts = navOptions {
popUpTo(0) { saveState = true } // any popUpToId works for option-property assertions
launchSingleTop = true
restoreState = true
}
assertTrue(opts.shouldLaunchSingleTop(), "launchSingleTop must be true")
assertTrue(opts.shouldRestoreState(), "restoreState must be true")
// popUpToInclusive defaults to false; saveState=true is captured via
// shouldPopUpToSaveState (see assertion below).
assertTrue(opts.shouldPopUpToSaveState(), "popUpTo { saveState = true } must be set")
}
@Test
fun navigateToTab_extension_isPublicAndDefinedOnNavHostController() {
// Compile-time + reflection-light assertion: the function exists with the
// expected signature. If it disappears or its signature drifts, the test
// file no longer compiles, which itself is a failed test.
val fn: (androidx.navigation.NavHostController, Any) -> Unit = { c, route -> c.navigateToTab(route) }
assertNotNull(fn)
}
@Test
fun navigateToTab_lambda_setsAllFourFlagsTogether() {
// Belt-and-suspenders: a single test that the four flags fire together,
// not individually — UI-03 hard-coded contract.
val opts = navOptions {
popUpTo(42) { saveState = true }
launchSingleTop = true
restoreState = true
}
assertEquals(true, opts.shouldLaunchSingleTop())
assertEquals(true, opts.shouldRestoreState())
assertEquals(true, opts.shouldPopUpToSaveState())
}
}
```
The `navOptions { ... }` DSL builder is part of `androidx.navigation` and ships with
`navigation-compose 2.9.2`. The accessor methods `shouldLaunchSingleTop()`,
`shouldRestoreState()`, `shouldPopUpToSaveState()` are public on `NavOptions`.
NOTE: drop the `@Ignore` import + annotations — the test file MUST run real assertions
on every commonTest invocation.
If `navOptions { ... }` or the `shouldXxx()` accessors are NOT publicly exposed by
nav-compose 2.9.2 K/N artifact (some methods may be marked `internal` on iOS), fall
back to capturing the lambda via a fake `NavOptionsBuilder`-like recorder. The
PATTERNS.md test note (lines 411-413) anticipates this: "If TestNavHostController
is unavailable in CMP commonTest, assert by capturing a fake builder."
Implementation guidance for fake-builder fallback:
- Build a thin wrapper class that records `popUpToId`, `popUpToBuilder.saveState`,
`launchSingleTop`, `restoreState` from method calls.
- Apply the navigateToTab lambda body (replicated) to the wrapper.
- Assert all four flags are recorded.
Choose whichever path compiles cleanly under the actual 2.9.2 API surface. The unit
semantics — V-01: four flags set — must hold either way.
./gradlew :composeApp:commonTest --tests "dev.ulfrx.recipe.navigation.NavigationTest" -q
- `grep -c '@Ignore' composeApp/src/commonTest/kotlin/dev/ulfrx/recipe/navigation/NavigationTest.kt` returns 0
- `grep -c 'launchSingleTop' composeApp/src/commonTest/kotlin/dev/ulfrx/recipe/navigation/NavigationTest.kt` returns at least 2
- `grep -c 'restoreState' composeApp/src/commonTest/kotlin/dev/ulfrx/recipe/navigation/NavigationTest.kt` returns at least 2
- `grep -c 'saveState' composeApp/src/commonTest/kotlin/dev/ulfrx/recipe/navigation/NavigationTest.kt` returns at least 2
- `grep -c 'navigateToTab' composeApp/src/commonTest/kotlin/dev/ulfrx/recipe/navigation/NavigationTest.kt` returns at least 1
- `./gradlew :composeApp:commonTest --tests "dev.ulfrx.recipe.navigation.NavigationTest" -q` exits 0 (V-01 anchor passes)
NavigationTest contains 3 passing assertions covering the four-flag contract (V-01). The @Ignore annotations and import are gone. UI-03 has its first piece of automated coverage.
- iOS K/N compile green: `./gradlew :composeApp:compileKotlinIosSimulatorArm64 -q` exits 0
- Navigation test passes: `./gradlew :composeApp:commonTest --tests "dev.ulfrx.recipe.navigation.NavigationTest" -q` exits 0
- iOS framework links: `./gradlew :composeApp:linkDebugFrameworkIosSimulatorArm64 -q` exits 0
- Default tab is Planner: `head -100 composeApp/src/commonMain/kotlin/dev/ulfrx/recipe/navigation/BottomBarDestination.kt | grep 'val Default' | grep -q 'Planner'`
- All 4 tab graphs declared and consumed: `grep -cE 'navigation<(Planner|Recipes|Pantry|Shopping)Graph>' composeApp/src/commonMain/kotlin/dev/ulfrx/recipe/navigation/RootNavHost.kt` returns 4
1. Routes.kt declares 8 @Serializable types: PlannerGraph/PlannerHome, RecipesGraph/RecipesHome, PantryGraph/PantryHome, ShoppingGraph/ShoppingHome.
2. BottomBarDestination enum declares 4 entries in D-03 order (Planner, Recipes, Pantry, Shopping); Planner is the Default; only Recipes + Pantry have hasSearch=true.
3. NavExtensions.navigateToTab applies popUpTo(findStartDestination().id) { saveState = true }; launchSingleTop = true; restoreState = true (UI-03 / RESEARCH § Pattern 1).
4. RootNavHost hosts a single root NavHost with 4 nested navigation() sub-graphs starting at PlannerGraph; each composable<*Home> block retrieves the parent graph's NavBackStackEntry for VM scoping (RESEARCH § Pattern 2).
5. strings.xml gains 9 shared shell/search keys (4 tab labels + 2 search placeholders + 3 search a11y strings) with verbatim Polish copy from UI-SPEC § Copywriting Contract; all 7 pre-existing auth_* keys preserved.
6. V-01 anchor: NavigationTest passes 3 assertions covering the four-flag contract.
7. iOS K/N compile is green — confirms Material Icons Outlined imports resolve cleanly (carry-over from plan 02.1-01 assumption A2).