36 KiB
36 KiB
phase, plan, type, wave, depends_on, files_modified, autonomous, requirements, tags, must_haves
| phase | plan | type | wave | depends_on | files_modified | autonomous | requirements | tags | must_haves | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| 02.1 | 04 | execute | 2 |
|
|
true |
|
|
|
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.
<execution_context> @$HOME/.claude/get-shit-done/workflows/execute-plan.md @$HOME/.claude/get-shit-done/templates/summary.md </execution_context>
@.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):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
NavOptionsBuilderinstance manually (or use Navigation Compose'snavOptions { ... }builder) and apply the lambda fromnavigateToTabto it, then assert the resultingNavOptionsproperties.
```xml
<!-- Phase 2.1 — App shell navigation tab labels (UI-03, CONTEXT D-03) -->
<string name="shell_tab_planner">Planer</string>
<string name="shell_tab_recipes">Przepisy</string>
<string name="shell_tab_pantry">Spiżarnia</string>
<string name="shell_tab_shopping">Zakupy</string>
<!-- Phase 2.1 — Search affordance placeholders (UI-10, CONTEXT D-06) -->
<string name="search_placeholder_recipes">Szukaj przepisów…</string>
<string name="search_placeholder_pantry">Szukaj w spiżarni…</string>
<!-- Phase 2.1 — Search affordance a11y (UI-10, CONTEXT D-06/D-08) -->
<string name="search_open_a11y">Otwórz wyszukiwanie</string>
<string name="search_close_a11y">Zamknij wyszukiwanie</string>
<string name="search_clear_a11y">Wyczyść</string>
```
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
}
}
```
```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<PlannerGraph>(startDestination = PlannerHome) {
composable<PlannerHome> { 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<PlannerDetail>{ ... }
}
// ---- Recipes graph ----
navigation<RecipesGraph>(startDestination = RecipesHome) {
composable<RecipesHome> { 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<PantryGraph>(startDestination = PantryHome) {
composable<PantryHome> { 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<ShoppingGraph>(startDestination = ShoppingHome) {
composable<ShoppingHome> { 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.
```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.
<success_criteria>
- Routes.kt declares 8 @Serializable types: PlannerGraph/PlannerHome, RecipesGraph/RecipesHome, PantryGraph/PantryHome, ShoppingGraph/ShoppingHome.
- BottomBarDestination enum declares 4 entries in D-03 order (Planner, Recipes, Pantry, Shopping); Planner is the Default; only Recipes + Pantry have hasSearch=true.
- NavExtensions.navigateToTab applies popUpTo(findStartDestination().id) { saveState = true }; launchSingleTop = true; restoreState = true (UI-03 / RESEARCH § Pattern 1).
- 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).
- 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.
- V-01 anchor: NavigationTest passes 3 assertions covering the four-flag contract.
- iOS K/N compile is green — confirms Material Icons Outlined imports resolve cleanly (carry-over from plan 02.1-01 assumption A2). </success_criteria>