From 5deddda9c0ed7a6f7dd7dece0b99a0b6cc87ef23 Mon Sep 17 00:00:00 2001 From: Alan Silva Date: Tue, 3 Nov 2026 17:14:41 +0000 Subject: [PATCH] Shell: system Back returns to the previous tab At a tab's root the system Back now returns to the tab opened before it, through a most-recent-first stack of visited tabs without duplicates. Every tab change (tap, Ctrl+Tab, a routed open) records it. Pages over the shell, Settings and a page in the open item's pane still close first; with no history Back reaches the platform as before. Only the shown tab's detail pane answers Back now. --- app/lib/shell/adaptive_shell.dart | 51 ++++- app/lib/shell/detail_pane_navigator.dart | 12 +- app/lib/shell/tab_history.dart | 44 ++++ app/test/shell/tab_history_back_test.dart | 262 ++++++++++++++++++++++ 4 files changed, 356 insertions(+), 13 deletions(-) create mode 100644 app/lib/shell/tab_history.dart create mode 100644 app/test/shell/tab_history_back_test.dart diff --git a/app/lib/shell/adaptive_shell.dart b/app/lib/shell/adaptive_shell.dart index b321b04d..3eecfc4b 100644 --- a/app/lib/shell/adaptive_shell.dart +++ b/app/lib/shell/adaptive_shell.dart @@ -12,6 +12,7 @@ import 'list_detail.dart'; import 'list_pane_widths.dart'; import 'shell_bar.dart'; import 'shell_list_shortcuts.dart'; +import 'tab_history.dart'; class AdaptiveShell extends StatefulWidget { const AdaptiveShell({ @@ -51,6 +52,10 @@ class AdaptiveShell extends StatefulWidget { class _AdaptiveShellState extends State { late AppDestination _selected; final Set _visited = {}; + final TabHistory _history = TabHistory(); + // Whether a navigator inside each destination (an open item's pane) has a + // page of its own for the system Back to close first. + final Map _nestedCanPop = {}; final ShellBarRegistry _bar = ShellBarRegistry(); late final ListPaneWidths _paneWidths = ListPaneWidths( store: widget.listPaneWidthStore, @@ -79,6 +84,7 @@ class _AdaptiveShellState extends State { super.didUpdateWidget(oldWidget); final destination = widget.destination; if (destination != null) { + _history.record(_selected, destination); _selected = destination; _visited.add(destination); } @@ -91,6 +97,7 @@ class _AdaptiveShellState extends State { return; } setState(() { + _history.record(_selected, destination); _selected = destination; _visited.add(destination); }); @@ -139,13 +146,19 @@ class _AdaptiveShellState extends State { final item = destinationDetails(destination); return KeyedSubtree( key: ValueKey(destination), - child: ShellBarScope( - registry: _bar, - destination: destination, - child: _visited.contains(destination) - ? widget.destinationBodies[destination]?.call(context) ?? - Center(child: Text('${item.label} — Not implemented')) - : const SizedBox.shrink(), + child: NotificationListener( + onNotification: (notification) { + _nestedCanPop[destination] = notification.canHandlePop; + return false; + }, + child: ShellBarScope( + registry: _bar, + destination: destination, + child: _visited.contains(destination) + ? widget.destinationBodies[destination]?.call(context) ?? + Center(child: Text('${item.label} — Not implemented')) + : const SizedBox.shrink(), + ), ), ); }).toList(); @@ -198,12 +211,16 @@ class _AdaptiveShellState extends State { // The scaffolds below swap the system insets for their bars' // heights; panes beside a list read the real ones from here. final system = MediaQuery.paddingOf(context); - // A page (Settings) closes to Pipelines on the system Back too. The - // scope is always there, so opening the page never remounts the shell. + // A page (Settings) closes to Pipelines on the system Back too; at a + // tab's root Back returns to the tab opened before it. Only with neither + // does Back reach the platform, so Android's (predictive) Back closes the + // app only from the first tab. Pages pushed over the shell (an item, + // Search, a dialog) pop before this scope is asked. The scope is always + // there, so opening the page never remounts the shell. Widget backable(Widget child) => PopScope( - canPop: !page, + canPop: !page && _history.isEmpty, onPopInvokedWithResult: (didPop, _) { - if (!didPop) _closePage(); + if (!didPop) _back(page: page); }, child: child, ); @@ -242,6 +259,18 @@ class _AdaptiveShellState extends State { /// Leaves a page destination (Settings) for the tab it belongs to. void _closePage() => _select(shellTabFor(_selected)); + /// The system Back the shell handles: it closes a page, or else returns to + /// the previous tab unless the open item's own pane closes a page first. + void _back({required bool page}) { + if (page) { + _closePage(); + return; + } + if (_nestedCanPop[shellTabFor(_selected)] ?? false) return; + final previous = _history.takePrevious(); + if (previous != null) _select(previous); + } + /// Handles this before focused text controls can insert or traverse on /// Ctrl+Tab. The handler is scoped to the shell's lifetime, not onboarding. /// diff --git a/app/lib/shell/detail_pane_navigator.dart b/app/lib/shell/detail_pane_navigator.dart index e10e8141..afcb9881 100644 --- a/app/lib/shell/detail_pane_navigator.dart +++ b/app/lib/shell/detail_pane_navigator.dart @@ -12,7 +12,8 @@ import '../ui/adaptive/host.dart'; /// /// The item is this navigator's first page under a fixed key, so a rebuilt /// item updates in place and is never remounted. The system Back pops a page -/// pushed here before it leaves the item. Opening a different item +/// pushed here before it leaves the item (or the shell's previous tab), in +/// the shown tab only. Opening a different item /// ([identity] changes) closes any page the previous item had pushed, so the /// pane shows the newly selected item. class DetailPaneNavigator extends StatefulWidget { @@ -44,8 +45,15 @@ class _DetailPaneNavigatorState extends State { final Page root = usesCupertinoHost(context) ? CupertinoPage(key: _rootKey, child: widget.child) : MaterialPage(key: _rootKey, child: widget.child); + // Only the shown tab's pane answers the system Back: a page left open in + // another tab's pane stays there while Back acts on the current tab. The + // route asks every handler on it, so a hidden pane also ignores the call. + final shown = TickerMode.valuesOf(context).enabled; return NavigatorPopHandler( - onPopWithResult: (_) => _navigator.currentState?.maybePop(), + enabled: shown, + onPopWithResult: (_) { + if (shown) _navigator.currentState?.maybePop(); + }, child: Navigator( key: _navigator, pages: [root], diff --git a/app/lib/shell/tab_history.dart b/app/lib/shell/tab_history.dart new file mode 100644 index 00000000..e937bb17 --- /dev/null +++ b/app/lib/shell/tab_history.dart @@ -0,0 +1,44 @@ +import 'destination.dart'; + +/// The tabs the operator left, most recent first, for the system Back. +/// +/// Every tab change (a tap, Ctrl+Tab, a search result or notification opening +/// another tab) goes through [record]: the tab being left moves to the top +/// and the tab being opened leaves the stack, so each tab appears at most once +/// and the current tab is never in it. A page that belongs to a tab +/// (Settings, of Pipelines) is that tab here. +/// +/// [takePrevious] steps back: it removes the top tab and returns it, and the +/// next [record] that opens that tab does not push the tab being left, so Back +/// never builds a forward trail. +class TabHistory { + final List _tabs = []; + AppDestination? _returningTo; + + /// The left tabs, most recent first. + List get tabs => List.unmodifiable(_tabs); + + bool get isEmpty => _tabs.isEmpty; + + /// Notes a change of the shown destination from [from] to [to]. + void record(AppDestination from, AppDestination to) { + final left = shellTabFor(from); + final opened = shellTabFor(to); + if (left == opened) return; + final returning = _returningTo == opened; + _returningTo = null; + _tabs.remove(opened); + if (returning) return; + _tabs + ..remove(left) + ..insert(0, left); + } + + /// The tab Back returns to, removed from the stack; null when empty. + AppDestination? takePrevious() { + if (_tabs.isEmpty) return null; + final previous = _tabs.removeAt(0); + _returningTo = previous; + return previous; + } +} diff --git a/app/test/shell/tab_history_back_test.dart b/app/test/shell/tab_history_back_test.dart new file mode 100644 index 00000000..2ec52868 --- /dev/null +++ b/app/test/shell/tab_history_back_test.dart @@ -0,0 +1,262 @@ +import 'package:flutter/material.dart'; +import 'package:flutter/services.dart'; +import 'package:flutter_test/flutter_test.dart'; +import 'package:pipelines_app/application/app_route.dart'; +import 'package:pipelines_app/application/app_router.dart'; +import 'package:pipelines_app/shell/adaptive_shell.dart'; +import 'package:pipelines_app/shell/destination.dart'; +import 'package:pipelines_app/shell/detail_pane_navigator.dart'; +import 'package:pipelines_app/shell/tab_history.dart'; + +/// Records the platform's own Back (closing the app) instead of running it. +List _recordExits(WidgetTester tester) { + final exits = []; + final messenger = tester.binding.defaultBinaryMessenger; + messenger.setMockMethodCallHandler(SystemChannels.platform, (call) async { + if (call.method == 'SystemNavigator.pop') exits.add(call.method); + return null; + }); + addTearDown( + () => messenger.setMockMethodCallHandler(SystemChannels.platform, null), + ); + return exits; +} + +Future _back(WidgetTester tester) async { + await tester.binding.handlePopRoute(); + await tester.pumpAndSettle(); +} + +Future _tapTab(WidgetTester tester, AppDestination tab) async { + await tester.tap(find.byKey(ValueKey('shell.destination.${tab.name}'))); + await tester.pumpAndSettle(); +} + +Map _bodies({ + Map overrides = const {}, +}) => { + for (final destination in AppDestination.values) + destination: (_) => Center(child: Text('body ${destination.name}')), + ...overrides, +}; + +void _expectShown(AppDestination destination) => + expect(find.text('body ${destination.name}'), findsOneWidget); + +void main() { + group('TabHistory', () { + test('keeps left tabs most recent first, without duplicates', () { + final history = TabHistory(); + history.record(AppDestination.pipelines, AppDestination.runs); + history.record(AppDestination.runs, AppDestination.chat); + history.record(AppDestination.chat, AppDestination.pipelines); + expect(history.tabs, [AppDestination.chat, AppDestination.runs]); + history.record(AppDestination.pipelines, AppDestination.runs); + expect(history.tabs, [AppDestination.pipelines, AppDestination.chat]); + }); + + test('a page counts as its tab, and Back builds no forward trail', () { + final history = TabHistory(); + history.record(AppDestination.runs, AppDestination.pipelines); + history.record(AppDestination.pipelines, AppDestination.settings); + expect(history.tabs, [AppDestination.runs]); + history.record(AppDestination.settings, AppDestination.chat); + expect(history.tabs, [AppDestination.pipelines, AppDestination.runs]); + + expect(history.takePrevious(), AppDestination.pipelines); + history.record(AppDestination.chat, AppDestination.pipelines); + expect(history.tabs, [AppDestination.runs]); + expect(history.takePrevious(), AppDestination.runs); + history.record(AppDestination.pipelines, AppDestination.runs); + expect(history.isEmpty, isTrue); + expect(history.takePrevious(), isNull); + }); + }); + + testWidgets('Back returns through the visited tabs, then to the platform', ( + tester, + ) async { + final exits = _recordExits(tester); + await tester.pumpWidget( + MaterialApp(home: AdaptiveShell(destinationBodies: _bodies())), + ); + await _tapTab(tester, AppDestination.runs); + await _tapTab(tester, AppDestination.chat); + // Revisiting Runs moves it to the top instead of adding it twice. + await _tapTab(tester, AppDestination.runs); + await _tapTab(tester, AppDestination.chat); + _expectShown(AppDestination.chat); + + await _back(tester); + _expectShown(AppDestination.runs); + await _back(tester); + _expectShown(AppDestination.pipelines); + expect(exits, isEmpty); + + // The initial tab with nothing open: the platform's Back applies. + await _back(tester); + _expectShown(AppDestination.pipelines); + expect(exits, ['SystemNavigator.pop']); + }); + + testWidgets('Ctrl+Tab tab changes are part of the history', (tester) async { + final exits = _recordExits(tester); + await tester.pumpWidget( + MaterialApp(home: AdaptiveShell(destinationBodies: _bodies())), + ); + await tester.sendKeyDownEvent(LogicalKeyboardKey.controlLeft); + await tester.sendKeyEvent(LogicalKeyboardKey.tab); + await tester.sendKeyUpEvent(LogicalKeyboardKey.controlLeft); + await tester.pumpAndSettle(); + _expectShown(AppDestination.runs); + + await _back(tester); + _expectShown(AppDestination.pipelines); + expect(exits, isEmpty); + }); + + testWidgets('a page open in the tab closes before Back changes tabs', ( + tester, + ) async { + final exits = _recordExits(tester); + await tester.pumpWidget( + MaterialApp( + home: AdaptiveShell( + destinationBodies: _bodies( + overrides: { + AppDestination.chat: (context) => Center( + child: TextButton( + onPressed: () => Navigator.of(context).push( + MaterialPageRoute( + builder: (_) => const Scaffold(body: Text('open item')), + ), + ), + child: const Text('body chat'), + ), + ), + }, + ), + ), + ), + ); + await _tapTab(tester, AppDestination.runs); + await _tapTab(tester, AppDestination.chat); + await tester.tap(find.text('body chat')); + await tester.pumpAndSettle(); + expect(find.text('open item'), findsOneWidget); + + await _back(tester); + expect(find.text('open item'), findsNothing); + _expectShown(AppDestination.chat); + + await _back(tester); + _expectShown(AppDestination.runs); + expect(exits, isEmpty); + }); + + testWidgets('a page in the open item\'s pane closes before Back changes ' + 'tabs, and only in the shown tab', (tester) async { + final exits = _recordExits(tester); + Widget pane(String name) => DetailPaneNavigator( + child: Builder( + builder: (context) => Center( + child: TextButton( + onPressed: () => Navigator.of( + context, + ).push(MaterialPageRoute(builder: (_) => Text('$name page'))), + child: Text('body $name'), + ), + ), + ), + ); + await tester.pumpWidget( + MaterialApp( + home: AdaptiveShell( + destinationBodies: _bodies( + overrides: { + AppDestination.runs: (_) => pane('runs'), + AppDestination.chat: (_) => pane('chat'), + }, + ), + ), + ), + ); + await _tapTab(tester, AppDestination.runs); + await tester.tap(find.text('body runs')); + await tester.pumpAndSettle(); + await _tapTab(tester, AppDestination.chat); + await tester.tap(find.text('body chat')); + await tester.pumpAndSettle(); + expect(find.text('chat page'), findsOneWidget); + + await _back(tester); + expect(find.text('chat page'), findsNothing); + _expectShown(AppDestination.chat); + // Runs' own pane page was left alone. + expect(find.text('runs page', skipOffstage: false), findsOneWidget); + + await _back(tester); + expect(find.text('runs page'), findsOneWidget); + expect(exits, isEmpty); + }); + + testWidgets('routed tab changes push the history; a page still closes to ' + 'its tab first', (tester) async { + final exits = _recordExits(tester); + late final AppRouterDelegate router; + AppDestination destinationOf(AppRoute route) => switch (route.kind) { + AppRouteKind.runs => AppDestination.runs, + AppRouteKind.chat => AppDestination.chat, + AppRouteKind.settings => AppDestination.settings, + _ => AppDestination.pipelines, + }; + AppRoute routeOf(AppDestination destination) => switch (destination) { + AppDestination.runs => AppRoute.runs, + AppDestination.chat => AppRoute.chat, + AppDestination.settings => AppRoute.settings, + _ => AppRoute.pipelines, + }; + router = AppRouterDelegate( + initial: AppRoute.runs, + cupertino: false, + builder: (_, route) => AdaptiveShell( + destination: destinationOf(route), + onDestinationSelected: (value) => router.goTo(routeOf(value)), + destinationBodies: _bodies(), + ), + ); + addTearDown(router.dispose); + final provider = PlatformRouteInformationProvider( + initialRouteInformation: RouteInformation(uri: Uri.parse('/runs')), + ); + addTearDown(provider.dispose); + await tester.pumpWidget( + MaterialApp.router( + routerDelegate: router, + routeInformationParser: const AppRouteParser(), + routeInformationProvider: provider, + ), + ); + await tester.pumpAndSettle(); + + // A programmatic open (a search result or notification) changes tabs. + router.goTo(AppRoute.chatSession('s')); + await tester.pumpAndSettle(); + _expectShown(AppDestination.chat); + router.goTo(AppRoute.settings); + await tester.pumpAndSettle(); + _expectShown(AppDestination.settings); + + // Settings closes to Pipelines first, as it always has. + await _back(tester); + expect(router.route, AppRoute.pipelines); + await _back(tester); + expect(router.route.kind, AppRouteKind.chat); + await _back(tester); + expect(router.route, AppRoute.runs); + expect(exits, isEmpty); + await _back(tester); + expect(exits, ['SystemNavigator.pop']); + await tester.pumpWidget(const SizedBox.shrink()); + }); +}