Merge dev into feature branch

apps/mobile/packages/features/client/client_main/lib/src/presentation/blocs/client_main_cubit.dart

@@ -1,20 +1,34 @@
 import 'package:flutter_bloc/flutter_bloc.dart';
 import 'package:flutter_modular/flutter_modular.dart';
 import 'package:krow_core/core.dart';
-import 'client_main_state.dart';
+import 'package:client_main/src/presentation/blocs/client_main_state.dart';
 
-class ClientMainCubit extends Cubit<ClientMainState> implements Disposable {
+/// Cubit that manages the client app's main navigation state.
+///
+/// Tracks the active bottom bar tab and controls tab visibility
+/// based on the current route.
+class ClientMainCubit extends Cubit<ClientMainState>
+    with BlocErrorHandler<ClientMainState>
+    implements Disposable {
+  /// Creates a [ClientMainCubit] and starts listening for route changes.
   ClientMainCubit() : super(const ClientMainState()) {
     Modular.to.addListener(_onRouteChanged);
     _onRouteChanged();
   }
 
+  /// Routes that should hide the bottom navigation bar.
   static const List<String> _hideBottomBarPaths = <String>[
     ClientPaths.completionReview,
     ClientPaths.awaitingApproval,
   ];
 
+  /// Updates state when the current route changes.
+  ///
+  /// Detects the active tab from the route path and determines
+  /// whether the bottom bar should be visible.
   void _onRouteChanged() {
+    if (isClosed) return;
+
     final String path = Modular.to.path;
     int newIndex = state.currentIndex;
 
@@ -41,6 +55,9 @@ class ClientMainCubit extends Cubit<ClientMainState> implements Disposable {
     }
   }
 
+  /// Navigates to the tab at [index] via Modular safe navigation.
+  ///
+  /// State update happens automatically via [_onRouteChanged].
   void navigateToTab(int index) {
     if (index == state.currentIndex) return;
 
@@ -61,7 +78,6 @@ class ClientMainCubit extends Cubit<ClientMainState> implements Disposable {
         Modular.to.toClientReports();
         break;
     }
-    // State update will happen via _onRouteChanged
   }
 
   @override

apps/mobile/packages/features/client/client_main/lib/src/presentation/blocs/client_main_state.dart

@@ -1,14 +1,20 @@
 import 'package:equatable/equatable.dart';
 
+/// State for [ClientMainCubit] representing bottom navigation status.
 class ClientMainState extends Equatable {
+  /// Creates a [ClientMainState] with the given tab index and bar visibility.
   const ClientMainState({
     this.currentIndex = 2, // Default to Home
     this.showBottomBar = true,
   });
 
+  /// Index of the currently active bottom navigation tab.
   final int currentIndex;
+
+  /// Whether the bottom navigation bar should be visible.
   final bool showBottomBar;
 
+  /// Creates a copy of this state with updated fields.
   ClientMainState copyWith({int? currentIndex, bool? showBottomBar}) {
     return ClientMainState(
       currentIndex: currentIndex ?? this.currentIndex,