TF-4141 Add Action required folder to left menu

lib/features/mailbox/presentation/extensions/handle_action_required_tab_extension.dart

@@ -0,0 +1,91 @@
+import 'package:jmap_dart_client/jmap/core/unsigned_int.dart';
+import 'package:jmap_dart_client/jmap/mail/mailbox/mailbox.dart';
+import 'package:model/mailbox/presentation_mailbox.dart';
+import 'package:tmail_ui_user/features/base/base_mailbox_controller.dart';
+import 'package:tmail_ui_user/features/mailbox/presentation/extensions/list_mailbox_node_extension.dart';
+import 'package:tmail_ui_user/features/mailbox/presentation/extensions/presentation_mailbox_extension.dart';
+import 'package:tmail_ui_user/features/mailbox/presentation/model/mailbox_node.dart';
+import 'package:tmail_ui_user/features/mailbox/presentation/model/mailbox_tree.dart';
+import 'package:tmail_ui_user/features/mailbox_dashboard/presentation/controller/mailbox_dashboard_controller.dart';
+import 'package:tmail_ui_user/features/mailbox_dashboard/presentation/extensions/handle_ai_action_extension.dart';
+import 'package:tmail_ui_user/main/routes/route_navigation.dart';
+
+extension HandleActionRequiredTabExtension on BaseMailboxController {
+  void setUpActionRequiredFolder(
+    MailboxDashBoardController dashboardController,
+  ) {
+    if (!dashboardController.isAiCapabilitySupported) return;
+
+    dashboardController.actionRequiredFolderController.getCountEmails(
+      session: dashboardController.sessionCurrent,
+      accountId: dashboardController.accountId.value,
+    );
+  }
+
+  void onActionRequiredFolderCountChanged(int count) {
+    if (count > 0) {
+      _addActionRequiredFolder(count);
+    } else {
+      _removeActionRequiredFolder();
+    }
+  }
+
+  void _addActionRequiredFolder(int count) {
+    final folder = _buildActionRequiredFolder(count);
+
+    _addToDefaultMailboxTree(folder);
+    _addToAllMailboxes(folder);
+  }
+
+  PresentationMailbox _buildActionRequiredFolder(int count) {
+    final base = PresentationMailbox.actionRequiredFolder;
+
+    return base.copyWith(
+      displayName:
+          currentContext != null ? base.getDisplayName(currentContext!) : null,
+      totalEmails: TotalEmails(UnsignedInt(count)),
+      unreadEmails: UnreadEmails(UnsignedInt(count)),
+    );
+  }
+
+  void _addToDefaultMailboxTree(PresentationMailbox folder) {
+    final root = defaultMailboxTree.value.root;
+    final children = List<MailboxNode>.from(root.childrenItems ?? []);
+
+    children.insertAfterStarredOrInbox(MailboxNode(folder));
+
+    defaultMailboxTree.value = MailboxTree(
+      root.copyWith(children: children),
+    );
+  }
+
+  void _addToAllMailboxes(PresentationMailbox folder) {
+    if (_allMailboxesContains(folder.id)) return;
+    allMailboxes.add(folder);
+  }
+
+  void _removeActionRequiredFolder() {
+    final folder = PresentationMailbox.actionRequiredFolder;
+
+    _removeFromDefaultMailboxTree(folder.id);
+    _removeFromAllMailboxes(folder.id);
+  }
+
+  void _removeFromDefaultMailboxTree(MailboxId folderId) {
+    final root = defaultMailboxTree.value.root;
+    final children = List<MailboxNode>.from(root.childrenItems ?? [])
+      ..removeWhere((node) => node.item.id == folderId);
+
+    defaultMailboxTree.value = MailboxTree(
+      root.copyWith(children: children),
+    );
+  }
+
+  void _removeFromAllMailboxes(MailboxId folderId) {
+    allMailboxes.removeWhere((mailbox) => mailbox.id == folderId);
+  }
+
+  bool _allMailboxesContains(MailboxId id) {
+    return allMailboxes.any((mailbox) => mailbox.id == id);
+  }
+}

lib/features/mailbox/presentation/extensions/list_mailbox_node_extension.dart

@@ -5,20 +5,60 @@ import 'package:tmail_ui_user/features/mailbox/presentation/model/mailbox_node.d
 extension ListMailboxNodeExtension on List<MailboxNode> {
   List<MailboxId> get mailboxIds => map((node) => node.item.id).toList();
 
+  /// Insert [newNode] after Inbox if present, otherwise at the beginning.
   void insertAfterInbox(MailboxNode newNode) {
-    final alreadyExists = any((node) => node.item.id == newNode.item.id);
-    if (alreadyExists) return;
-
-    final index = indexWhere(
-      (node) =>
-          node.item.role?.value == PresentationMailbox.inboxRole ||
-          node.item.name?.name.toLowerCase() == 'inbox',
+    insertAfterByPriority(
+      newNode,
+      [_isInbox],
     );
+  }
 
-    if (index != -1) {
-      insert(index + 1, newNode);
-    } else {
-      insert(0, newNode);
+  /// Insert [newNode] after Starred if present,
+  /// otherwise after Inbox, otherwise at the beginning.
+  void insertAfterStarredOrInbox(MailboxNode newNode) {
+    insertAfterByPriority(
+      newNode,
+      [
+        _isStarred,
+        _isInbox,
+      ],
+    );
+  }
+
+  /// Insert [newNode] after the first mailbox matching [priorities].
+  /// If none match, inserts at the beginning.
+  void insertAfterByPriority(
+    MailboxNode newNode,
+    List<bool Function(MailboxNode)> priorities,
+  ) {
+    if (_containsMailbox(newNode)) return;
+
+    for (final predicate in priorities) {
+      final index = indexWhere(predicate);
+      if (index != -1) {
+        insert(index + 1, newNode);
+        return;
+      }
     }
+
+    insert(0, newNode);
+  }
+
+  bool _isInbox(MailboxNode node) {
+    return node.item.role?.value == PresentationMailbox.inboxRole ||
+        _equalsIgnoreCase(node.item.name?.name, 'inbox');
+  }
+
+  bool _isStarred(MailboxNode node) {
+    return node.item.role?.value == PresentationMailbox.favoriteRole ||
+        _equalsIgnoreCase(node.item.name?.name, 'starred');
+  }
+
+  bool _containsMailbox(MailboxNode node) {
+    return any((e) => e.item.id == node.item.id);
+  }
+
+  bool _equalsIgnoreCase(String? value, String expected) {
+    return value != null && value.toLowerCase() == expected;
   }
 }

lib/features/mailbox/presentation/extensions/presentation_mailbox_extension.dart

@@ -17,6 +17,8 @@ extension PresentationMailboxExtension on PresentationMailbox {
           return AppLocalizations.of(context).inboxMailboxDisplayName;
         case PresentationMailbox.favoriteRole:
           return AppLocalizations.of(context).favoriteMailboxDisplayName;
+        case PresentationMailbox.actionRequiredRole:
+          return AppLocalizations.of(context).actionRequiredMailboxDisplayName;
         case PresentationMailbox.archiveRole:
           return AppLocalizations.of(context).archiveMailboxDisplayName;
         case PresentationMailbox.draftsRole:
@@ -44,6 +46,10 @@ extension PresentationMailboxExtension on PresentationMailbox {
       switch(role!.value.toLowerCase()) {
         case PresentationMailbox.inboxRole:
           return appLocalizations.inboxMailboxDisplayName;
+        case PresentationMailbox.favoriteRole:
+          return appLocalizations.favoriteMailboxDisplayName;
+        case PresentationMailbox.actionRequiredRole:
+          return appLocalizations.actionRequiredMailboxDisplayName;
         case PresentationMailbox.archiveRole:
           return appLocalizations.archiveMailboxDisplayName;
         case PresentationMailbox.draftsRole:
@@ -73,6 +79,8 @@ extension PresentationMailboxExtension on PresentationMailbox {
           return imagePaths.icMailboxInbox;
         case PresentationMailbox.favoriteRole:
           return imagePaths.icMailboxFavorite;
+        case PresentationMailbox.actionRequiredRole:
+          return imagePaths.icMailboxActionRequired;
         case PresentationMailbox.draftsRole:
           return imagePaths.icMailboxDrafts;
         case PresentationMailbox.outboxRole:

lib/features/mailbox/presentation/mailbox_controller.dart

@@ -69,6 +69,7 @@ import 'package:tmail_ui_user/features/mailbox/domain/usecases/subaddressing_int
 import 'package:tmail_ui_user/features/mailbox/domain/usecases/subscribe_mailbox_interactor.dart';
 import 'package:tmail_ui_user/features/mailbox/domain/usecases/subscribe_multiple_mailbox_interactor.dart';
 import 'package:tmail_ui_user/features/mailbox/presentation/action/mailbox_ui_action.dart';
+import 'package:tmail_ui_user/features/mailbox/presentation/extensions/handle_action_required_tab_extension.dart';
 import 'package:tmail_ui_user/features/mailbox/presentation/extensions/handle_favorite_tab_extension.dart';
 import 'package:tmail_ui_user/features/mailbox/presentation/extensions/presentation_mailbox_extension.dart';
 import 'package:tmail_ui_user/features/mailbox/presentation/mixin/mailbox_widget_mixin.dart';
@@ -264,6 +265,7 @@ class MailboxController extends BaseMailboxController
       (failure) {
         if (failure is GetAllMailboxFailure) {
           addFavoriteFolderToMailboxList();
+          setUpActionRequiredFolder(mailboxDashBoardController);
           mailboxDashBoardController.updateRefreshAllMailboxState(Left(RefreshAllMailboxFailure()));
           showRetryToast(failure);
         }
@@ -271,6 +273,7 @@ class MailboxController extends BaseMailboxController
       (success) {
         if (success is GetAllMailboxSuccess) {
           addFavoriteFolderToMailboxList();
+          setUpActionRequiredFolder(mailboxDashBoardController);
           mailboxDashBoardController.updateRefreshAllMailboxState(Right(RefreshAllMailboxSuccess()));
           _handleCreateDefaultFolderIfMissing(mailboxDashBoardController.mapDefaultMailboxIdByRole);
           _handleDataFromNavigationRouter();
@@ -280,6 +283,7 @@ class MailboxController extends BaseMailboxController
           }
         } else if (success is CreateDefaultMailboxAllSuccess) {
           addFavoriteFolderToMailboxList();
+          setUpActionRequiredFolder(mailboxDashBoardController);
         }
       });
   }
@@ -434,6 +438,11 @@ class MailboxController extends BaseMailboxController
         );
       }
     });
+
+    ever(
+      mailboxDashBoardController.actionRequiredFolderController.actionRequiredFolderCount,
+      onActionRequiredFolderCountChanged,
+    );
   }
 
   void _handleMarkEmailsAsReadOrUnread({