Fix behavior of 'g' key to return to aggregate view from top-level detail view, refine navigation docs (#26)

Fixes #21

---------

Co-authored-by: Claude <noreply@anthropic.com>

Author: wesm

docs/guide/navigation.md

@@ -74,6 +74,8 @@ alt="Categories view">
 Press `d` to view all transactions ungrouped in chronological order,
 or press `Enter` from any aggregate row to see the transactions for that specific item.
 
+To return to an aggregate view, press `g` or `Escape`.
+
 **Columns displayed:**
 
 - Date
@@ -168,6 +170,11 @@ This powerful feature lets you combine multiple filters to answer very specific
 
 Press `Escape` to navigate backwards through your drill-down path, removing one filter level at a time.
 
+**From top-level detail view:**
+
+- When viewing all transactions (not drilled down), press `g` or `Escape` to return to an aggregate view
+- Both keys restore your previous aggregate view (Merchant, Category, Group, or Account)
+
 **Single-level drill-down with sub-grouping:**
 
 - From `Merchants > Amazon (by Category)`, press `Escape` to return to `Merchants > Amazon` (clears sub-grouping)
@@ -304,10 +311,10 @@ Here are some practical examples of using moneyflow's navigation features to ans
 
 | Key | Action |
 |-----|--------|
-| `g` | Cycle views (Merchant/Category/Group/Account) |
+| `g` | Cycle aggregate views, or return to aggregate view from detail view |
 | `d` | Detail view (all transactions) |
 | `Enter` | Drill down |
-| `Escape` | Go back |
+| `Escape` | Go back (or return to aggregate view from detail view) |
 | `s` | Cycle sort field |
 | `v` | Reverse sort |
 | `/` | Search |

moneyflow/app_controller.py

@@ -29,7 +29,15 @@
 from .data_manager import DataManager
 from .formatters import ViewPresenter
 from .logging_config import get_logger
-from .state import AppState, SortDirection, SortMode, TimeFrame, TransactionEdit, ViewMode
+from .state import (
+    AppState,
+    NavigationState,
+    SortDirection,
+    SortMode,
+    TimeFrame,
+    TransactionEdit,
+    ViewMode,
+)
 from .time_navigator import TimeNavigator
 from .view_interface import IViewPresenter
 
@@ -407,11 +415,7 @@ def _prepare_aggregate_view(self, view_mode: ViewMode):
     def switch_to_merchant_view(self):
         """Switch to merchant aggregation view."""
         self.state.view_mode = ViewMode.MERCHANT
-        self.state.selected_merchant = None
-        self.state.selected_category = None
-        self.state.selected_group = None
-        self.state.selected_account = None
-        self.state.clear_selection()  # Clear all multi-select
+        self.state.clear_drill_down_and_selection()
         # Reset sort to valid field for aggregate views (now includes field name)
         if self.state.sort_by not in [SortMode.MERCHANT, SortMode.COUNT, SortMode.AMOUNT]:
             self.state.sort_by = SortMode.AMOUNT
@@ -420,35 +424,23 @@ def switch_to_merchant_view(self):
     def switch_to_category_view(self):
         """Switch to category aggregation view."""
         self.state.view_mode = ViewMode.CATEGORY
-        self.state.selected_merchant = None
-        self.state.selected_category = None
-        self.state.selected_group = None
-        self.state.selected_account = None
-        self.state.clear_selection()  # Clear all multi-select
+        self.state.clear_drill_down_and_selection()
         if self.state.sort_by not in [SortMode.CATEGORY, SortMode.COUNT, SortMode.AMOUNT]:
             self.state.sort_by = SortMode.AMOUNT
         self.refresh_view()
 
     def switch_to_group_view(self):
         """Switch to group aggregation view."""
         self.state.view_mode = ViewMode.GROUP
-        self.state.selected_merchant = None
-        self.state.selected_category = None
-        self.state.selected_group = None
-        self.state.selected_account = None
-        self.state.clear_selection()  # Clear all multi-select
+        self.state.clear_drill_down_and_selection()
         if self.state.sort_by not in [SortMode.GROUP, SortMode.COUNT, SortMode.AMOUNT]:
             self.state.sort_by = SortMode.AMOUNT
         self.refresh_view()
 
     def switch_to_account_view(self):
         """Switch to account aggregation view."""
         self.state.view_mode = ViewMode.ACCOUNT
-        self.state.selected_merchant = None
-        self.state.selected_category = None
-        self.state.selected_group = None
-        self.state.selected_account = None
-        self.state.clear_selection()  # Clear all multi-select
+        self.state.clear_drill_down_and_selection()
         if self.state.sort_by not in [SortMode.ACCOUNT, SortMode.COUNT, SortMode.AMOUNT]:
             self.state.sort_by = SortMode.AMOUNT
         self.refresh_view()
@@ -457,15 +449,37 @@ def switch_to_detail_view(self, set_default_sort: bool = True):
         """
         Switch to transaction detail view (ungrouped).
 
+        Saves current state to navigation history if switching from an aggregate view,
+        so that pressing Esc or 'g' can restore the previous view.
+
         Args:
             set_default_sort: If True, set default sort (Date descending)
         """
+        # Save current state to navigation history if we're in an aggregate view
+        # This allows Esc/'g' to return to the correct aggregate view
+        if self.state.view_mode in [
+            ViewMode.MERCHANT,
+            ViewMode.CATEGORY,
+            ViewMode.GROUP,
+            ViewMode.ACCOUNT,
+        ]:
+            self.state.navigation_history.append(
+                NavigationState(
+                    view_mode=self.state.view_mode,
+                    cursor_position=0,  # Don't preserve cursor when switching with 'd'
+                    scroll_y=0.0,
+                    sort_by=self.state.sort_by,
+                    sort_direction=self.state.sort_direction,
+                    selected_merchant=self.state.selected_merchant,
+                    selected_category=self.state.selected_category,
+                    selected_group=self.state.selected_group,
+                    selected_account=self.state.selected_account,
+                    sub_grouping_mode=self.state.sub_grouping_mode,
+                )
+            )
+
         self.state.view_mode = ViewMode.DETAIL
-        self.state.selected_merchant = None
-        self.state.selected_category = None
-        self.state.selected_group = None
-        self.state.selected_account = None
-        self.state.clear_selection()  # Clear all multi-select
+        self.state.clear_drill_down_and_selection()
         if set_default_sort:
             self.state.sort_by = SortMode.DATE
             self.state.sort_direction = SortDirection.DESC
@@ -881,7 +895,7 @@ def _get_action_hints(self) -> str:
             ):
                 return "Esc/g=Back | m=✏️ Merchant | c=✏️ Category | h=Hide | x=Delete | Space=Select | Ctrl-A=SelectAll"
             else:
-                return "g=Group | m=✏️ Merchant | c=✏️ Category | h=Hide | x=Delete | Space=Select | Ctrl-A=SelectAll"
+                return "Esc/g=Group | m=✏️ Merchant | c=✏️ Category | h=Hide | x=Delete | Space=Select | Ctrl-A=SelectAll"
 
     # Edit Orchestration Methods
 

moneyflow/state.py

@@ -222,6 +222,21 @@ def clear_selection(self):
         self.selected_ids.clear()
         self.selected_group_keys.clear()
 
+    def clear_drill_down_and_selection(self):
+        """
+        Clear all drill-down filters and selections.
+
+        This is a common operation when switching views or returning to top-level.
+        Clears:
+        - All drill-down filters (merchant, category, group, account)
+        - Multi-select state (transaction IDs and group keys)
+        """
+        self.selected_merchant = None
+        self.selected_category = None
+        self.selected_group = None
+        self.selected_account = None
+        self.clear_selection()
+
     def set_timeframe(
         self,
         timeframe: TimeFrame,
@@ -460,7 +475,8 @@ def cycle_grouping(self) -> str:
         Cycle through grouping modes.
 
         If drilled down: Cycle sub-groupings within current filter
-        If not drilled down: Cycle top-level aggregation views
+        If in top-level detail view: Go back to previous aggregate view (or MERCHANT)
+        If in aggregate view: Cycle top-level aggregation views
 
         When cycling views, if currently sorting by an aggregate field (MERCHANT,
         CATEGORY, GROUP, or ACCOUNT), the sort field is updated to match the new
@@ -476,9 +492,32 @@ def cycle_grouping(self) -> str:
         if self.is_drilled_down():
             return self.cycle_sub_grouping()
 
-        # Only cycle if in an aggregation view (not DETAIL)
+        # If in top-level detail view, go back to aggregate view (like Escape)
         if self.view_mode == ViewMode.DETAIL:
-            return ""
+            # Try to restore from navigation history first
+            if self.navigation_history:
+                nav_state = self.navigation_history.pop()
+                self.view_mode = nav_state.view_mode
+                self.sort_by = nav_state.sort_by
+                self.sort_direction = nav_state.sort_direction
+                # Restore any drill-down context from history
+                self.selected_merchant = nav_state.selected_merchant
+                self.selected_category = nav_state.selected_category
+                self.selected_group = nav_state.selected_group
+                self.selected_account = nav_state.selected_account
+                self.sub_grouping_mode = nav_state.sub_grouping_mode
+                # Return friendly name for the restored view
+                view_names = {
+                    ViewMode.MERCHANT: "Merchants",
+                    ViewMode.CATEGORY: "Categories",
+                    ViewMode.GROUP: "Groups",
+                    ViewMode.ACCOUNT: "Accounts",
+                }
+                return view_names.get(nav_state.view_mode, "")
+            else:
+                # No history - default to merchant view
+                self.view_mode = ViewMode.MERCHANT
+                return "Merchants"
 
         # Clear any drill-down selections when switching views
         self.selected_merchant = None

tests/test_app_controller.py

@@ -941,6 +941,39 @@ async def test_switch_to_detail_view_preserve_sort(self, controller, mock_view):
         assert controller.state.sort_by == SortMode.AMOUNT
         assert controller.state.sort_direction == SortDirection.ASC
 
+    async def test_switch_to_detail_view_saves_navigation_history(self, controller, mock_view):
+        """Test that switching from aggregate to detail view saves navigation history."""
+        # Start in category view
+        controller.state.view_mode = ViewMode.CATEGORY
+        controller.state.sort_by = SortMode.CATEGORY
+        controller.state.sort_direction = SortDirection.ASC
+
+        # Switch to detail view
+        controller.switch_to_detail_view(set_default_sort=True)
+
+        # Should have saved the category view to navigation history
+        assert len(controller.state.navigation_history) == 1
+        nav_state = controller.state.navigation_history[0]
+        assert nav_state.view_mode == ViewMode.CATEGORY
+        assert nav_state.sort_by == SortMode.CATEGORY
+        assert nav_state.sort_direction == SortDirection.ASC
+
+        # Now in detail view
+        assert controller.state.view_mode == ViewMode.DETAIL
+
+    async def test_switch_to_detail_view_from_detail_no_duplicate_history(
+        self, controller, mock_view
+    ):
+        """Test that switching from detail to detail doesn't add duplicate history."""
+        # Already in detail view
+        controller.state.view_mode = ViewMode.DETAIL
+
+        # Switch to detail view again
+        controller.switch_to_detail_view(set_default_sort=True)
+
+        # Should not have added to navigation history
+        assert len(controller.state.navigation_history) == 0
+
     async def test_view_switch_clears_selections(self, controller, mock_view):
         """Test that switching views clears all drill-down selections."""
         # Set up some selections

tests/test_state.py

@@ -1143,6 +1143,50 @@ def test_cycle_grouping_works_normally_when_not_drilled_down(self):
         assert state.view_mode == ViewMode.CATEGORY
         assert result == "Categories"
 
+    def test_cycle_grouping_from_detail_view_with_history_restores_previous_view(self):
+        """Pressing 'g' from top-level DETAIL view with navigation history should restore previous view."""
+        state = AppState()
+        state.view_mode = ViewMode.DETAIL
+        state.sort_by = SortMode.DATE
+        state.sort_direction = SortDirection.ASC
+
+        # Simulate having navigation history from a previous CATEGORY view
+        nav_state = NavigationState(
+            view_mode=ViewMode.CATEGORY,
+            sort_by=SortMode.CATEGORY,
+            sort_direction=SortDirection.DESC,
+            cursor_position=5,
+            scroll_y=100.0,
+        )
+        state.navigation_history.append(nav_state)
+
+        result = state.cycle_grouping()
+
+        # Should restore to CATEGORY view with previous sort settings
+        assert state.view_mode == ViewMode.CATEGORY
+        assert state.sort_by == SortMode.CATEGORY
+        assert state.sort_direction == SortDirection.DESC
+        assert result == "Categories"
+        # Navigation history should be consumed
+        assert len(state.navigation_history) == 0
+
+    def test_cycle_grouping_from_detail_view_without_history_defaults_to_merchant(self):
+        """Pressing 'g' from top-level DETAIL view without history should default to MERCHANT view."""
+        state = AppState()
+        state.view_mode = ViewMode.DETAIL
+        state.sort_by = SortMode.DATE
+        state.sort_direction = SortDirection.ASC
+        # No navigation history
+
+        result = state.cycle_grouping()
+
+        # Should default to MERCHANT view
+        assert state.view_mode == ViewMode.MERCHANT
+        # Sort settings should be preserved from current state
+        assert state.sort_by == SortMode.DATE
+        assert state.sort_direction == SortDirection.ASC
+        assert result == "Merchants"
+
     def test_cycle_sub_grouping_resets_date_sort_to_amount(self):
         """When cycling from detail to aggregated sub-grouping, should reset DATE sort to AMOUNT."""
         state = AppState()