Navigation State Repository
Component Detail
Description
Persists tab index and navigation stack snapshots across app sessions using local storage, so users with motor fatigue return to their last position after backgrounding or restarting the app. Backed by shared_preferences or Hive for lightweight key-value persistence.
navigation-state-repository
Summaries
The Navigation State Repository ensures that users — particularly those with motor fatigue who expend significant physical effort to navigate the application — never lose their place when the app is backgrounded, interrupted by a phone call, or restarted. For our target users, re-navigating to a deeply nested screen is not merely inconvenient; it is a genuine accessibility barrier. By persisting navigation state across sessions, this component reduces the physical cost of using the app and increases the likelihood that users complete their intended tasks. This directly supports user satisfaction, long-term retention, and positions the product as genuinely designed for its audience rather than superficially accessible.
This is a low-complexity data persistence component with no external service dependencies, making it one of the lowest-risk deliverables in the navigation stack. It uses either shared_preferences or Hive for key-value storage — the choice should be standardized with the rest of the app's local persistence strategy to avoid introducing a second storage library. Delivery is straightforward, but it must be coordinated with the Tab State Manager, which consumes it for restore operations. A critical integration concern is the `clearOnLogout()` method: it must be wired into the authentication flow before any user-facing release to prevent one user's navigation state from persisting into another user's session.
Testing should cover cold-start, backgrounding, role switch, and logout scenarios.
Navigation State Repository provides a thin persistence facade over shared_preferences or Hive, serializing tab index as an integer and route stacks as JSON-encoded string lists. `saveActiveTab(index)` and `loadActiveTab()` handle single integer persistence; `saveTabRouteStack(tabIndex, stack)` encodes a `List
`clearNavigationState()` removes all nav keys; `clearOnLogout()` should be an alias or superset of this, called from the auth state change handler. Keep this layer free of Flutter widget dependencies for easy unit testing.
Responsibilities
- Save active tab index on tab change
- Persist navigation route stack per tab branch
- Restore navigation state on app resume or cold start
- Clear stale navigation state on logout or role switch
Interfaces
saveActiveTab(index)
loadActiveTab()
saveTabRouteStack(tabIndex, stack)
loadTabRouteStack(tabIndex)
clearNavigationState()
clearOnLogout()