navigation

# Alkaa Navigation ## Overview Alkaa uses event-driven navigation: UI components send named action events, and the system resolves where to go. Navigation is never triggered directly from UI or ViewModels — it always flows through `NavEventController`. ## Required Files per Navigation Change | File | Package | Purpose | |------|---------|---------| | `*Event.kt` | `com.escodro.navigationapi.event` | Defines action events | | `*Destination.kt` | `com.escodro.navigationapi.destination` | Defines typed routes | | `*NavGraph.kt` | feature module | Registers entries and sends events | Both `*Event.kt` and `*Destination.kt` live in `features/navigation-api`. → See `references/CODE_PATTERNS.md` for Kotlin examples of all three files. ## Steps 1. **Create the Event** — Name after the action, not the destination (`OnEditClick`, not `NavigateToEdit`) → see `references/CODE_PATTERNS.md` 2. **Create the Destination** — Add `@Serializable`; choose interface based on screen type → see `references/CODE_PATTERNS.md` 3. **Add a NavGraph Entry** — `entry<Destination>` block with appropriate transition spec → see `references/CODE_PATTERNS.md` 4. **Hoist Navigation** — Composables receive lambdas; NavGraph calls `navEventController.sendEvent()` → see `references/CODE_PATTERNS.md` ## Destination Interface Rules | Interface | When to use | |-----------|-------------| | `TopLevel` | Bottom-nav root screens only (requires `title`, `icon`, `@CommonParcelize`) | | `TopAppBarVisible` | Dialogs, bottom sheets, non-full-screen destinations | | Neither | Regular full-screen push destinations | Also register `TopLevel` and `TopAppBarVisible` destinations in the corresponding sets in `Destination.kt`. ## Checklist - [ ] Event named after an action (verb phrase: `On*Click`, `On*Save`) - [ ] Destination annotated with `@Serializable` - [ ] `TopLevel` only for bottom-nav root screens (with `@CommonParcelize`, `title`, `icon`) - [ ] `TopAppBarVisible` only for dialogs/sheets/non-full-screen - [ ] `TopLevel`/`TopAppBarVisible` destinations registered in `Destination.kt` sets - [ ] NavGraph `entry<>` block exists for each new destination - [ ] Navigation events sent from within NavGraph lambda, not from composables or ViewModels - [ ] Back navigation uses `Event.OnBack`, not custom events ## Common Mistakes | Mistake | Fix | |---------|-----| | `navEventController.sendEvent()` in a ViewModel | Must not leave the NavGraph — pass navigation as lambda callbacks instead | | `navEventController.sendEvent()` inside a `@Composable` | Move to NavGraph `entry<>` block via lambda callback | | Event named `NavigateToDetail` or `GoToSettings` | Name after the action: `OnDetailClick`, `OnSettingsClick` | | Destination without `@Serializable` | Add annotation — Navigation3 requires it | | Full-screen destination with `TopAppBarVisible` | Remove — use only for dialogs/sheets | | New feature with no `NavGraph` implementation | Create `*NavGraph.kt` and bind in Koin module |