diff --git a/docs/MOBILE/00-agent-development-rules.md b/docs/MOBILE/00-agent-development-rules.md index 5ef0a8b7..b28a9cb2 100644 --- a/docs/MOBILE/00-agent-development-rules.md +++ b/docs/MOBILE/00-agent-development-rules.md @@ -42,9 +42,10 @@ Follow Dart standards strictly. * **Data Transformation**: MUST reside in **Repositories** (Data Connect layer). * *Forbidden*: Parsing JSON in the UI or Domain. * **Pattern**: Repositories map Data Connect models to Domain entities. -* **Navigation Logic**: MUST reside in **Flutter Modular Routes**. - * *Forbidden*: `Navigator.push` with hardcoded widgets. - * **Pattern**: Use named routes via `Modular.to.navigate()`. +* **Navigation Logic**: MUST reside in **Flutter Modular Routes** and use **Safe Navigation**. + * *Forbidden*: `Navigator.push` with hardcoded widgets or direct `Modular.to.pop()` / `Modular.to.navigate()`. + * **Pattern**: Use `popSafe()`, `safeNavigate()`, `safePush()`, etc., from `NavigationExtensions`. Prefer **Typed Navigators** (e.g., `Modular.to.toHome()`). + * **Fallback**: All navigation MUST have a fallback to the Home page implemented in `NavigationExtensions`. * **Session Management**: MUST reside in **DataConnectService** via **SessionHandlerMixin**. * **Pattern**: Automatic token refresh, auth state listening, and role-based validation. * **UI Reaction**: **SessionListener** widget wraps the entire app and responds to session state changes. diff --git a/docs/MOBILE/01-architecture-principles.md b/docs/MOBILE/01-architecture-principles.md index b37833ca..564df8e2 100644 --- a/docs/MOBILE/01-architecture-principles.md +++ b/docs/MOBILE/01-architecture-principles.md @@ -178,9 +178,11 @@ All backend access is unified through `DataConnectService` with integrated sessi - **Zero Direct Imports**: `import 'package:feature_a/...'` is FORBIDDEN inside `package:feature_b`. - Exception: Shared packages like `domain`, `core`, and `design_system` are always accessible. -- **Navigation**: Use named routes via Flutter Modular: - - **Pattern**: `Modular.to.navigate('route_name')` - - **Configuration**: Routes defined in `module.dart` files; constants in `paths.dart` +- **Navigation**: Use **Typed Navigators** and **Safe Navigation** via Flutter Modular: + - **Safe Methods**: ALWAYS use `safeNavigate()`, `safePush()`, `popSafe()`, and `safePushNamedAndRemoveUntil()` from `NavigationExtensions`. + - **Fallback**: All safe methods automatically fall back to the Home page (Staff or Client) if the target route is invalid or the operation fails. + - **Typed Navigator Pattern**: Prefer using typed methods on `Modular.to` (e.g., `Modular.to.toShiftDetails(id)`) which are implemented in `ClientNavigator` and `StaffNavigator` using these safe extensions. + - **Configuration**: Routes defined in `module.dart` files; constants in `paths.dart`. - **Data Sharing**: Features do not share state directly. Shared data accessed through: - **Domain Repositories**: Centralized data sources (e.g., `AuthRepository`) - **Session Stores**: `StaffSessionStore` and `ClientSessionStore` for app-wide user context diff --git a/docs/MOBILE/02-design-system-usage.md b/docs/MOBILE/02-design-system-usage.md index eeab7c90..0ad635e6 100644 --- a/docs/MOBILE/02-design-system-usage.md +++ b/docs/MOBILE/02-design-system-usage.md @@ -1,4 +1,4 @@ -# 03 - Design System Usage Guide +# 02 - Design System Usage Guide This document defines the mandatory standards for designing and implementing user interfaces across all applications and feature packages using the shared `apps/mobile/packages/design_system`. @@ -88,7 +88,9 @@ Padding( The design system provides "Smart Widgets" – these are high-level UI components that encapsulate both styling and standard behavior. - **Standard Widgets**: Prefer standard Flutter Material widgets (e.g., `ElevatedButton`) but styled via the central theme. -- **Custom Components**: Use `design_system` widgets for non-standard elements or wisgets that has similar design across various features, if provided. +- **Custom Components**: Use `design_system` widgets for non-standard elements or widgets that have similar design across various features, if provided. +- **Navigation in Widgets**: Widgets that trigger navigation (e.g., Back buttons in `UiAppBar`) MUST use `Modular.to.popSafe()` or typed navigator methods to prevent blank screens or unexpected application states during stack pops. + - **Composition**: Prefer composing standard widgets over creating deep inheritance hierarchies in features. ## 9. Theme Configuration & Usage