Merge pull request #318 from woltapp/improve-coffee-majer-documentation

[Demo app] Improve coffee maker demo documentation for Flutter & Friends workshop

coffee_maker_navigator_2/lib/app/app.dart

@@ -9,6 +9,12 @@ class CoffeeMakerApp extends StatelessWidget {
 
   @override
   Widget build(BuildContext context) {
+    /// STEP #3: Provide the DependencyInjector to the widget tree.
+    ///
+    /// Here, we wrap the entire widget tree with the `DependencyInjector` widget.
+    /// This makes the DI system available to all widgets in the tree, allowing them
+    /// to access the active dependency containers. By doing this, any widget can
+    /// easily retrieve the necessary dependencies it needs.
     return DependencyInjector(
       child: Builder(builder: (context) {
         final appLevelDependencyContainer = DependencyInjector.container<

coffee_maker_navigator_2/lib/app/router/entities/app_route_configuration.dart

@@ -31,6 +31,11 @@ class AppRouteConfiguration {
   final AppRouteUriTemplate appRouteUriTemplate;
   final QueryParams queryParams;
 
+  /// STEP #16: Define the AppRouteConfiguration class.
+  ///
+  /// This class represents the navigation state by combining a static route template
+  /// from [AppRouteUriTemplate] with dynamic query parameters. It is used in handling
+  /// deep linking, dynamic navigation, and keeping the app's state in sync with the browser's URL.
   const AppRouteConfiguration({
     required this.appRouteUriTemplate,
     this.queryParams = const {},

coffee_maker_navigator_2/lib/app/router/entities/app_route_page.dart

@@ -19,22 +19,16 @@ import 'package:flutter/material.dart';
 import 'package:wolt_di/wolt_di.dart';
 import 'package:wolt_modal_sheet/wolt_modal_sheet.dart';
 
-/// `AppRoutePage` is a sealed class that extends Flutter's [Page] class. It serves as a base
-/// class for all route pages within the application, defining a consistent interface and behavior
-/// for routes.
+/// STEP #7: Define the route pages.
 ///
-/// One of the main benefits of a sealed class is that it guarantees exhaustiveness.
-/// Since all possible subclasses of `AppRoutePage` are known at compile time, the application can
-/// ensure that every route is explicitly handled. This helps prevent errors that can arise from
-/// unhandled routes or navigation scenarios, leading to more robust and predictable routing behavior.
-/// When working with pattern matching or switch cases on instances of `AppRoutePage`, the compiler
-/// can enforce that all cases are covered, reducing the risk of runtime errors.
+/// The `AppRoutePage` class is a base class for all route pages in the application.
+/// It extends Flutter's [Page] class, providing a consistent way to define the pages
+/// and their behavior for navigation.
 ///
-///   Each subclass of `AppRoutePage` must specify an [AppRouteUriTemplate] that represents the
-///   static route template associated with the page. The `queryParams` getter allows each page
-///   to define any dynamic query parameters it might need. This is crucial for passing state or
-///   configuration data through the URL, supporting more sophisticated navigation scenarios and
-///   state management.x
+/// Using a sealed class provides exhaustiveness that helps to ensure that all possible route types
+/// are defined and handled explicitly. This makes the navigation system more robust and
+/// predictable by preventing errors from unhandled routes. It allows for clear and
+/// exhaustive pattern matching when managing navigation, reducing the chance of runtime errors.
 sealed class AppRoutePage<T> extends Page<T> {
   const AppRoutePage({LocalKey? key}) : super(key: key);
 

coffee_maker_navigator_2/lib/app/router/view/app_route_information_parser.dart

@@ -34,7 +34,7 @@ class AppRouteInformationParser
     extends RouteInformationParser<AppRouteConfiguration> {
   const AppRouteInformationParser();
 
-  /// Parses the given [RouteInformation] into an [AppRouteConfiguration].
+  /// Step #13: Parse the given [RouteInformation] into an [AppRouteConfiguration].
   ///
   /// This method extracts the URI from the [RouteInformation], identifies the route path using
   /// [AppRouteUriTemplate.findFromUri], and captures any query parameters. The resulting
@@ -51,7 +51,8 @@ class AppRouteInformationParser
     );
   }
 
-  /// Restores the [RouteInformation] from a given [AppRouteConfiguration].
+  /// Step #19: Restores the [RouteInformation] from a given
+  /// [AppRouteConfiguration].
   ///
   /// This method converts the application's current navigation state back into a URI,
   /// which can be used to update the browser's address bar, ensuring consistency between

coffee_maker_navigator_2/lib/app/router/view/app_route_observer.dart

@@ -35,6 +35,13 @@ class AppRouteObserver extends RouteObserver<PageRoute<void>> {
     }
   }
 
+  /// STEP #12: Update the System UI Overlay Style based on the current route.
+  ///
+  /// This method updates the system UI overlay style, such as the status bar and navigation bar
+  /// colors, based on the active route. It checks whether the current route has a bottom
+  /// navigation bar (like the Orders page) and adjusts the UI elements accordingly to ensure
+  /// a consistent look and feel throughout the app. This is done using the provided color scheme
+  /// and helps maintain visual consistency as users navigate between different parts of the app.
   void _updateSystemUIOverlayStyle(Route<void> route) {
     SystemUIAnnotationWrapper.setSystemUIOverlayStyle(
       colorScheme,

coffee_maker_navigator_2/lib/app/router/view/app_router_delegate.dart

@@ -45,39 +45,67 @@ class AppRouterDelegate extends RouterDelegate<AppRouteConfiguration>
     ]).addListener(notifyListeners);
   }
 
+  /// STEP #6: Build the navigation stack.
+  ///
+  /// This method is responsible for building the `Navigator` widget, which manages
+  /// the app's navigation stack. It uses the list of pages provided by the `RouterViewModel` to
+  /// define what pages are currently displayed. The `Navigator` widget is the View part of MVVM,
+  /// and it updates automatically whenever the ViewModel (RouterViewModel) changes, ensuring the
+  /// UI reflects the current navigation state. This connection allows for a reactive and dynamic
+  /// navigation experience in the app.
   @override
   Widget build(BuildContext context) {
     return Navigator(
       key: navigatorKey,
-      pages: routerViewModel.pages
-          .value, // The list of pages defining the current navigation stack.
+      pages: routerViewModel.pages.value,
       onPopPage: (route, result) {
+        /// STEP #9: Handle the pop page event.
+        ///
+        /// This callback is invoked when a [Route] created from a [Page] in the [pages] list is
+        /// popped. In other words, it handles the scenario where a declaratively added route is
+        /// removed using an imperative pop call to the [Navigator] widget. For example, the back
+        /// button in the [AddWaterScreen] can trigger a pop event that removes the screen from the
+        ///
+        /// The `RouterViewModel` is notified about the page pop event, allowing it to update and sync
+        /// the [pages] list accordingly, ensuring that the navigation state remains consistent.
         routerViewModel.onPagePoppedImperatively();
         return route.didPop(result);
       },
       observers: [AppRouteObserver(Theme.of(context).colorScheme)],
     );
   }
 
-  /// Handles pop actions initiated by the operating system (e.g., back gestures or hardware
-  /// buttons). This method ensures that such interactions are managed consistently with the
-  /// app's navigation logic.
+  /// STEP #10: Handle the pop route event.
+  ///
+  /// This method manages pop actions initiated by the operating system, such as back gestures or
+  /// hardware back button presses on devices like Android. It ensures these interactions are
+  /// handled consistently with the app's navigation logic as defined in the `RouterViewModel`,
+  /// which tracks and updates the list of pages in the navigation stack.
   @override
   Future<bool> popRoute() {
     return routerViewModel.onPagePoppedWithOperatingSystemIntent();
   }
 
+  /// STEP #17: Get the current route configuration.
+  ///
+  /// This method retrieves the current route configuration, which reflects the app's current
+  /// navigation state. The router widget calls this method whenever it needs to update the
+  /// browser's URL or sync the app state with the URL. This ensures that the displayed URL
+  /// accurately represents the current visible screen in the app.
   @override
   AppRouteConfiguration get currentConfiguration {
-    // Returns the current route configuration, used to update the browser's URL
-    // and keep it in sync with the application's state.
     return routerViewModel.onUriRestoration();
   }
 
+  /// STEP #14: Set a new navigation stack for the app configuration.
+  ///
+  /// This method updates the navigation stack based on a new route configuration. It is used to handle
+  /// changes such as URL updates or deep links, ensuring the app responds appropriately to these changes.
+  /// By parsing the new route configuration and updating the state in the `RouterViewModel`, the app
+  /// can dynamically adjust its navigation stack to reflect the user's intent, whether it's through
+  /// direct URL input, deep links, or other routing events.
   @override
   Future<void> setNewRoutePath(AppRouteConfiguration configuration) async {
-    // Updates the navigation stack based on a new route configuration, allowing
-    // the application to respond to changes such as URL updates or deep links.
     routerViewModel.onNewUriParsed(configuration);
   }
 }

coffee_maker_navigator_2/lib/app/router/view_model/router_view_model.dart

@@ -66,10 +66,24 @@ class RouterViewModel {
   ValueListenable<CoffeeMakerStep> get visibleOrderScreenNavBarTab =>
       _visibleOrderScreenNavBarTab;
 
+  /// STEP #4: Inject dependencies into the ViewModel's constructor.
+  ///
+  /// In this step, the AuthService and OnboardingService are injected into the
+  /// RouterViewModel through its constructor. These services together represent the Model
+  /// in the MVVM pattern, providing the data and business logic related to authentication
+  /// and onboarding. By injecting these services, the ViewModel can interact with the
+  /// underlying data and logic, allowing it to manage the state of the View.
   RouterViewModel({
     required this.authService,
     required this.onboardingService,
   }) {
+    /// STEP #5: Subscribe to authentication state changes.
+    ///
+    /// Here, we listen to changes in the user's authentication state by subscribing
+    /// to the `authStateListenable` from AuthService. This allows the ViewModel to
+    /// respond to changes in the Model (AuthService) and update the UI (the View) accordingly.
+    /// For instance, when the user logs in or out, the ViewModel updates the list of pages to be
+    /// displayed in the app, ensuring the UI always reflects the current authentication state.
     authService.authStateListenable.addListener(_authStateChangeSubscription);
   }
 
@@ -101,6 +115,11 @@ class RouterViewModel {
   void onDrawerDestinationSelected(
     AppNavigationDrawerDestination destination,
   ) {
+    /// STEP #8: Implement the navigation logic for drawer destinations in the ViewModel.
+    ///
+    /// This step defines how the app should respond when a user selects an item from the
+    /// navigation drawer. Based on the selected destination, the ViewModel updates the
+    /// page stack to display the appropriate screen(s).
     switch (destination) {
       case AppNavigationDrawerDestination.ordersScreen:
         _pages.value = [OrdersRoutePage(_visibleOrderScreenNavBarTab)];
@@ -152,8 +171,9 @@ class RouterViewModel {
     }
   }
 
-  /// Handles the update of the routing URL (visible on the Browser address bar) when the app
-  /// navigation state changes.
+  /// Step #18: Handles the update of the routing URL (visible on the Browser
+  /// address bar) when the
+  /// app navigation state changes.
   ///
   /// This method is triggered by changes to either the [pages] list or the
   /// [visibleOrderScreenNavBarTab]. It constructs a new [AppRouteConfiguration]
@@ -171,6 +191,8 @@ class RouterViewModel {
     );
   }
 
+  /// Step #15: Respond to the parsing of a new URL route.
+  ///
   /// Responds to the parsing of a new URL route by the [RouteInformationParser] and returns sets
   /// the new navigation stack defined by the [pages] list based on the provided
   /// [AppRouteConfiguration].

coffee_maker_navigator_2/lib/app/ui/widgets/app_navigation_drawer.dart

@@ -5,8 +5,7 @@ enum AppNavigationDrawerDestination {
   ordersScreen(label: Text("Orders"), icon: Icon(Icons.coffee)),
   tutorialsScreen(
       label: Text("Tutorials"), icon: Icon(Icons.menu_book_outlined)),
-  logOut(label: Text("Log out"), icon: Icon(Icons.logout)),
-  ;
+  logOut(label: Text("Log out"), icon: Icon(Icons.logout));
 
   const AppNavigationDrawerDestination({
     required this.icon,
@@ -37,6 +36,13 @@ class AppNavigationDrawer extends StatelessWidget {
 
   @override
   Widget build(BuildContext context) {
+    /// STEP #11: Handle the back button press event.
+    ///
+    /// This callback manages back button presses from the operating system (e.g., gestures or hardware
+    /// buttons on Android) in this particular case, when the navigation drawer is open. Instead
+    /// of leaving the screen, it closes the drawer and returns `true` to indicate the event is
+    /// handled locally. If the drawer is not open, it returns `false`, allowing
+    /// the Router widget's `RootBackButtonDispatcher` content to handle the event.
     return BackButtonListener(
       onBackButtonPressed: () async {
         final scaffold = Scaffold.maybeOf(context);
@@ -47,7 +53,6 @@ class AppNavigationDrawer extends StatelessWidget {
 
           return true;
         }
-
         // If view is not open, return false to indicate that
         // the router should handle this.
         return false;

coffee_maker_navigator_2/lib/main.dart

@@ -6,7 +6,8 @@ import 'package:coffee_maker_navigator_2/app/di/coffee_maker_app_level_dependenc
 import 'package:coffee_maker_navigator_2/features/orders/di/orders_dependency_container.dart';
 import 'package:flutter/material.dart';
 
-void _registerDependencyContainerFactories(DependencyContainerManager manager) {
+void _registerFeatureLevelDependencyContainers(
+    DependencyContainerManager manager) {
   manager
     ..registerContainerFactory<OrdersDependencyContainer>(
         () => OrdersDependencyContainer())
@@ -25,13 +26,13 @@ void _registerDependencyContainerFactories(DependencyContainerManager manager) {
 |  | | AuthService             | | |       |  |    DependencyInjector       | |
 |  | +-------------------------+ | |       |  |          Widget             | |
 |  | | AuthRepository          | | |       |  |  +-----------------------+  | |
-|  | +-------------------------+ | |       |  |  | FeatureLevelDependency|  | |
-|  | | AuthRemoteDataSource    | | |       |  |  |        Container      |  | |
-|  | +-------------------------+ | |       |  |  | +-------------------+ |  | |
-|  | | RouterViewModel         | | |       |  |  | |      Feature      | |  | |
-|  | +-------------------------+ | |       |  |  | |    Screen Widget  | |  | |
-|  +-----------------------------+ |       |  |  | |                   | |  | |
-|                                  |       |  |  | +-------------------+ |  | |
+|  | +-------------------------+ | |       |  |  |                       |  | |
+|  | | AuthRemoteDataSource    | | |       |  |  |                       |  | |
+|  | +-------------------------+ | |       |  |  |                       |  | |
+|  | | RouterViewModel         | | |       |  |  |        Feature        |  | |
+|  | +-------------------------+ | |       |  |  |      Screen Widget    |  | |
+|  +-----------------------------+ |       |  |  |                       |  | |
+|                                  |       |  |  |                       |  | |
 |  +-----------------------------+ |       |  |  |                       |  | |
 |  | OrdersDependencyContainer   | |       |  |  +-----------------------+  | |
 |  | +-------------------------+ | |       |  +-----------------------------+ |
@@ -57,9 +58,26 @@ void _registerDependencyContainerFactories(DependencyContainerManager manager) {
 */
 Future<void> main() async {
   WidgetsFlutterBinding.ensureInitialized();
+
+  /// STEP #1: Initialize the dependency container manager with the App-level dependency container.
+  ///
+  /// The app-level dependency container is responsible for managing the dependencies used
+  /// as long as app is alive. These dependencies can be shared across multiple feature level
+  /// dependency containers. It is the only container that is initialized asynchronously.
   final dependencyContainerManager = DependencyContainerManager.instance;
   await dependencyContainerManager
       .init(CoffeeMakerAppLevelDependencyContainer());
-  _registerDependencyContainerFactories(dependencyContainerManager);
+
+  /// STEP #2: Register feature-level dependency containers.
+  ///
+  /// Here, we register dependency containers for specific features, like Orders, AddWater, and
+  /// LoginScreen with the `DependencyContainerManager`. Each feature has its own container to
+  /// manage its group of dependencies.
+  ///
+  /// This uses a Service Locator pattern, where dependencies are registered and retrieved as needed.
+  /// Additionally, the `DependencyContainerManager` automatically disposes of containers that
+  /// are no longer needed and have no active subscribers, helping manage resources efficiently.
+  _registerFeatureLevelDependencyContainers(dependencyContainerManager);
+
   runApp(const CoffeeMakerApp());
 }