From 82418d31a76548ef5d5965a4472582740036dbc6 Mon Sep 17 00:00:00 2001 From: Alan Silva Date: Thu, 12 Nov 2026 10:33:57 +0000 Subject: [PATCH 1/2] Place terminal action in phone chat bar Keep the Chats header clear at narrow widths by moving the phone terminal entry into the chat action bar and disabling the duplicate floating shortcut. Add focused widget coverage for the single terminal entry and header layout. --- app/lib/application/app_terminals.dart | 4 +- app/lib/application/pipelines_app.dart | 6 +- .../ui/sessions/chat_sessions_screen.dart | 41 +++--- app/notes/phone-chat-list-terminal-button.md | 67 +++++++++ .../phone_chat_terminal_entries_test.dart | 57 ++++++++ .../chat_list_terminal_action_test.dart | 127 ++++++++++++++++++ 6 files changed, 282 insertions(+), 20 deletions(-) create mode 100644 app/notes/phone-chat-list-terminal-button.md create mode 100644 app/test/application/phone_chat_terminal_entries_test.dart create mode 100644 app/test/features/chat/ui/sessions/chat_list_terminal_action_test.dart diff --git a/app/lib/application/app_terminals.dart b/app/lib/application/app_terminals.dart index 5b3e9dc8..3977467a 100644 --- a/app/lib/application/app_terminals.dart +++ b/app/lib/application/app_terminals.dart @@ -52,8 +52,8 @@ class AppTerminals { /// [shell] with the terminal panel, window or page around it, and the /// app's floating [windows] above both. - /// [onChat]: the phone shortcut that reopens the terminal shows on the - /// Chat tab only. + /// [onChat]: whether the phone shortcut that reopens the terminal shows on + /// this page. Pages whose own bar carries Terminal pass false. Widget surround(Widget shell, {bool onChat = true, Widget? windows}) => TerminalSurface( hub: hub, diff --git a/app/lib/application/pipelines_app.dart b/app/lib/application/pipelines_app.dart index 93eef0c5..a0953e1d 100644 --- a/app/lib/application/pipelines_app.dart +++ b/app/lib/application/pipelines_app.dart @@ -818,7 +818,11 @@ class _PipelinesAppState extends State valueListenable: _attentionCount, builder: (context, count, _) => _terminals.surround( _shellFor(route, count), - onChat: route.kind == AppRouteKind.chat, + // Every narrow Chat bar carries Terminal itself (the list's top bar + // and an open chat's bar, see terminalChatBarAction), so the floating + // bubble is off on every route. It otherwise covered the list's + // header and duplicated the open chat's Terminal entry. + onChat: false, windows: WindowHost(manager: _windows, reservesRail: true), ), ); diff --git a/app/lib/features/chat/ui/sessions/chat_sessions_screen.dart b/app/lib/features/chat/ui/sessions/chat_sessions_screen.dart index 7f3c192e..d789d670 100644 --- a/app/lib/features/chat/ui/sessions/chat_sessions_screen.dart +++ b/app/lib/features/chat/ui/sessions/chat_sessions_screen.dart @@ -11,6 +11,7 @@ import '../../../../ui/layout/content_width.dart'; import '../../../../core/api_gateway.dart'; import '../../../../shell/shell_bar.dart'; import '../../../../shell/shell_list_shortcuts.dart'; +import '../../../terminal/terminal_open_action.dart'; import '../../data/chat_repository.dart'; import '../../domain/chat_colors.dart'; import '../../domain/chat_cycle.dart'; @@ -381,7 +382,7 @@ class _ChatSessionsScreenState extends State { if (ShellBar.available(context)) { return ShellBar( active: widget.publishShellBar ?? widget.activeSessionId == null, - actions: _actions(), + actions: _actions(context), // The Chat tab counts chats with messages not yet seen. child: ShellBadge( kind: ShellBadgeKind.unread, @@ -396,7 +397,7 @@ class _ChatSessionsScreenState extends State { alignment: AlignmentDirectional.centerEnd, child: Row( mainAxisSize: MainAxisSize.min, - children: _actions(), + children: _actions(context), ), ), Expanded(child: body), @@ -406,7 +407,7 @@ class _ChatSessionsScreenState extends State { return Scaffold( extendBodyBehindAppBar: true, - appBar: SegmentedBar(title: 'Chats', actions: _actions()), + appBar: SegmentedBar(title: 'Chats', actions: _actions(context)), // The list scrolls behind the floating bar; New chat is the bar's // own action, so there is no second create button. body: body, @@ -415,18 +416,24 @@ class _ChatSessionsScreenState extends State { ); } - List _actions() => [ - ChatBarAction( - key: const Key('chat-new-chat'), - label: 'New chat', - onPressed: _newChat, - materialIcon: Icons.add, - ), - ChatBarAction( - key: const Key('chat-refresh'), - label: 'Refresh', - onPressed: _controller.refresh, - materialIcon: Icons.refresh, - ), - ]; + /// New chat, Refresh and, on a narrow layout, the terminal toggle (wide + /// layouts keep it on the shell bar, so it is null here). + List _actions(BuildContext context) { + final terminal = terminalChatBarAction(context); + return [ + ChatBarAction( + key: const Key('chat-new-chat'), + label: 'New chat', + onPressed: _newChat, + materialIcon: Icons.add, + ), + ChatBarAction( + key: const Key('chat-refresh'), + label: 'Refresh', + onPressed: _controller.refresh, + materialIcon: Icons.refresh, + ), + ?terminal, + ]; + } } diff --git a/app/notes/phone-chat-list-terminal-button.md b/app/notes/phone-chat-list-terminal-button.md new file mode 100644 index 00000000..d89d08da --- /dev/null +++ b/app/notes/phone-chat-list-terminal-button.md @@ -0,0 +1,67 @@ +# Phone chat list: terminal button over the Chats header + +## Defect +At 430px the floating terminal shortcut (`TerminalShortcutBubble`, end 12, +top = safe top + 64) sat on the chat list's `Chats` section header at +[370,64,48,48]. It hid the header's count and collapse chevron and left a +stray glyph beside it. Evidence: `/tmp/ui-review/base-light-430x900/07-chat.png`, +`/tmp/ui-review/chatmenus-light-430x900/01-chatlist-more.png`. + +Run 393 had removed a duplicate terminal icon from the narrow list bar, so the +list had only the floating bubble. + +## Change +- `lib/features/chat/ui/sessions/chat_sessions_screen.dart`: `_actions(context)` + now appends `terminalChatBarAction(context)` after New chat and Refresh. It is + null on wide layouts (the shell bar keeps Terminal there) and with no + terminal surface, so it appears only on a narrow layout with a surface. +- `lib/application/pipelines_app.dart`: the floating bubble's `onChat` is now + `false` on every route. On a narrow layout every Chat-tab bar carries Terminal + itself (the list's top bar, and an open chat's bar via + `chat_thread_view.dart`'s `terminalChatBarAction`), so the bubble has no + remaining place. The earlier rule (`kind == chat && chatSessionId != null`) + still showed it on an open chat, duplicating that chat's Terminal entry. +- `lib/application/app_terminals.dart`: doc comment for `surround(onChat:)` + now says pages whose own bar carries Terminal pass false. No behaviour change. + +Result on a phone: exactly one terminal entry on the chat list (top bar) and on +an open chat (its bar), and no floating control over any header. + +## Focused tests (memwatch, from app/) +- `test/application/phone_chat_terminal_entries_test.dart`: new, 2 tests at + 430x900 through the app shell. `/chat` and `/chat/abc123` each have no + `TerminalShortcutBubble` and exactly one Terminal `ChatBarAction`. + Against the previous `onChat` rule the open-chat test FAILS (the bubble is + shown), so it guards the reviewer's finding. Restored after that check. +- `test/features/chat/ui/sessions/chat_list_terminal_action_test.dart`: 4 tests. + Narrow top bar carries Terminal beside New chat and Refresh, and tapping it + toggles. The Chats heading sits below the bar. Wide has no list terminal. + No terminal surface has no list terminal. +- Users of the changed wiring, all in the same run: + - `test/application/pipelines_app_test.dart` + - `test/features/terminal/terminal_surface_test.dart` + - `test/features/chat/ui/sessions/chat_sessions_floating_bar_test.dart` + - `test/features/chat/ui/sessions/chat_sessions_screen_test.dart` + + Combined run of these six plus the list test: PASS 28/28 (`memwatch: PASS`, + exit 0), run after the final edit. +- Not re-run in this pass: `test/features/chat/shell/chat_shell_terminal_test.dart` + and `chat_shell_terminal_session_test.dart` (listed as users in an earlier + pass). The `onChat` change does not touch the shell's wide path. +- `tool/analyze.sh`: clean (0 errors, 0 warnings, 0 infos) after the final edit. + +## Not verified here +- No rendered capture. The before/after screenshots at 430x900 are for ui-review. +- The open-chat test checks the Terminal action by label, not by semantics + identifier. In the open chat's bar the identifier lookup found nothing even + though the action is present, so this is a limit of the probe, not evidence + of a missing entry. A capture is needed to confirm what is drawn. + +## Open limitations +- `TerminalShortcutBubble` is now never shown by the app shell (`onChat` is + always false). It and `TerminalSurface`'s shortcut code remain, with their + own tests. Removing them is a follow-up if the owner agrees. +- A narrow Chat-tab route with no chat bar would now have no terminal entry at + all. None was found in the code, but this was not exhaustively checked. +- The bubble's old top edge on an open chat was not checked against that chat's + bar; with the bubble gone that check is moot. diff --git a/app/test/application/phone_chat_terminal_entries_test.dart b/app/test/application/phone_chat_terminal_entries_test.dart new file mode 100644 index 00000000..d3676dff --- /dev/null +++ b/app/test/application/phone_chat_terminal_entries_test.dart @@ -0,0 +1,57 @@ +import 'package:flutter/material.dart'; +import 'package:flutter_test/flutter_test.dart'; +import 'package:pipelines_app/core/transport/pipelines_client.dart'; +import 'package:pipelines_app/features/chat/ui/sessions/chat_adaptive.dart'; +import 'package:pipelines_app/features/terminal/terminal_shortcut_bubble.dart'; +import 'package:pipelines_app/features/terminal/terminal_toggle_button.dart'; + +import '../core/transport/pipelines_client_test.dart' show FakeChannel; +import 'pipelines_app_test.dart' show pumpApp; + +/// On a phone the Chat tab has exactly one terminal entry: the bar's own +/// Terminal action. The floating shortcut bubble must not appear over the +/// chat list's header, nor beside an open chat's bar that already has it. + +Future _pumpAt(WidgetTester tester, String location) async { + tester.view.physicalSize = const Size(430, 900); + tester.view.devicePixelRatio = 1; + addTearDown(tester.view.resetPhysicalSize); + addTearDown(tester.view.resetDevicePixelRatio); + final channel = FakeChannel()..readyCompleter.complete(); + final client = PipelinesClient(channelFactory: (_) => channel); + final provider = PlatformRouteInformationProvider( + initialRouteInformation: RouteInformation(uri: Uri.parse(location)), + ); + addTearDown(provider.dispose); + await pumpApp(tester, channel: channel, client: client, provider: provider); + await tester.pump(); + await tester.pump(); +} + +/// The bar's Terminal actions on screen (a [ChatBarAction] carrying the +/// terminal toggle's label). +Finder _barTerminal() => find.byWidgetPredicate( + (w) => w is ChatBarAction && w.label == TerminalToggleButton.label, +); + +void main() { + testWidgets('phone chat list: one terminal entry, no floating bubble', ( + tester, + ) async { + await _pumpAt(tester, '/chat'); + + expect(find.byType(TerminalShortcutBubble), findsNothing); + expect(_barTerminal(), findsOneWidget); + expect(tester.takeException(), isNull); + }); + + testWidgets('phone open chat: one terminal entry, no floating bubble', ( + tester, + ) async { + await _pumpAt(tester, '/chat/abc123'); + + expect(find.byType(TerminalShortcutBubble), findsNothing); + expect(_barTerminal(), findsOneWidget); + expect(tester.takeException(), isNull); + }); +} diff --git a/app/test/features/chat/ui/sessions/chat_list_terminal_action_test.dart b/app/test/features/chat/ui/sessions/chat_list_terminal_action_test.dart new file mode 100644 index 00000000..998af4eb --- /dev/null +++ b/app/test/features/chat/ui/sessions/chat_list_terminal_action_test.dart @@ -0,0 +1,127 @@ +import 'package:flutter/material.dart'; +import 'package:flutter_test/flutter_test.dart'; +import 'package:pipelines_app/core/api_gateway.dart'; +import 'package:pipelines_app/features/chat/ui/sessions/chat_sessions_screen.dart'; +import 'package:pipelines_app/features/terminal/terminal_scope.dart'; +import 'package:pipelines_app/features/terminal/terminal_toggle_button.dart'; +import 'package:pipelines_app/ui/adaptive/segmented_bar.dart'; +import 'package:pipelines_app/ui/layout/section_heading.dart'; + +import 'chat_test_harness.dart'; +import 'fake_chat_gateway.dart'; + +/// The chat list's top bar carries Terminal beside New chat and Refresh on a +/// narrow layout, so the phone header below it has no floating terminal +/// shortcut over its count and collapse chevron. + +class _Actions implements TerminalActions { + int toggles = 0; + + @override + void toggle() => toggles++; + + @override + bool get claimsTabKeys => false; + + @override + Future openAt(ApiGateway gateway, String cwd) async => null; +} + +const _terminalIdentifier = 'chat-terminal-toggle'; + +Future _pumpList( + WidgetTester tester, { + required Size size, + TerminalActions? actions, +}) async { + tester.view.physicalSize = size; + tester.view.devicePixelRatio = 1; + addTearDown(tester.view.resetPhysicalSize); + addTearDown(tester.view.resetDevicePixelRatio); + final gateway = FakeChatGateway() + ..sessionsReply = {'chat_sessions': sampleSessions()}; + final list = ChatSessionsScreen( + gateway: gateway, + onOpen: (_) {}, + localStore: MemoryChatSessionLocalStore(), + ); + await tester.pumpWidget( + MaterialApp( + theme: ThemeData(platform: TargetPlatform.android), + home: MediaQuery( + data: MediaQueryData(size: size), + child: actions == null + ? list + : TerminalScope(actions: actions, child: list), + ), + ), + ); + await tester.pumpAndSettle(); +} + +void main() { + testWidgets('phone: Terminal sits in the top bar beside New chat and ' + 'Refresh, and is the only terminal entry on the list', (tester) async { + final actions = _Actions(); + await _pumpList(tester, size: const Size(430, 900), actions: actions); + + final bar = find.byType(SegmentedBar); + expect( + find.descendant( + of: bar, + matching: find.byKey(const Key('chat-new-chat')), + ), + findsOneWidget, + ); + expect( + find.descendant(of: bar, matching: find.byKey(const Key('chat-refresh'))), + findsOneWidget, + ); + final terminal = find.descendant( + of: bar, + matching: find.bySemanticsIdentifier(_terminalIdentifier), + ); + expect(terminal, findsOneWidget); + expect(find.byTooltip(TerminalToggleButton.label), findsOneWidget); + expect(find.byType(FloatingActionButton), findsNothing); + + await tester.tap(terminal); + await tester.pump(); + expect(actions.toggles, 1); + }); + + testWidgets('phone: the top bar sits above the Chats header, which keeps its ' + 'count and collapse chevron clear of it', (tester) async { + await _pumpList(tester, size: const Size(430, 900), actions: _Actions()); + + final bar = tester.getRect(find.byType(SegmentedBar)); + final heading = find.descendant( + of: find.byKey(const ValueKey('chat-section-Chats')), + matching: find.byType(SectionHeading), + ); + expect(heading, findsOneWidget); + final headerRect = tester.getRect(heading); + expect( + headerRect.top, + greaterThanOrEqualTo(bar.bottom), + reason: 'no top-bar control may cover the section header', + ); + expect(tester.takeException(), isNull); + }); + + testWidgets('a wide layout keeps Terminal on the shell bar, not the list ' + 'bar', (tester) async { + await _pumpList(tester, size: const Size(1200, 800), actions: _Actions()); + + expect(find.bySemanticsIdentifier(_terminalIdentifier), findsNothing); + }); + + testWidgets('with no terminal surface the list bar has no terminal entry', ( + tester, + ) async { + await _pumpList(tester, size: const Size(430, 900)); + + expect(find.bySemanticsIdentifier(_terminalIdentifier), findsNothing); + expect(find.byKey(const Key('chat-new-chat')), findsOneWidget); + }); +} From 77a88d09d30f52e2276228b05d2c4e83dc0270e2 Mon Sep 17 00:00:00 2001 From: Alan Silva Date: Thu, 12 Nov 2026 10:39:33 +0000 Subject: [PATCH 2/2] Make Settings a top-level navigation destination Show Back only when Settings is reached through a pushed route, and remove duplicate Settings controls where the shell already provides navigation. Update focused widget coverage and document the destination behavior. --- app/lib/application/pipelines_app.dart | 10 ++ app/lib/features/pipelines/screen.dart | 7 +- app/lib/shell/adaptive_shell.dart | 31 ++++- app/lib/shell/destination.dart | 7 +- app/lib/shell/navigation_rail.dart | 6 + app/notes/settings-destination-back.md | 72 +++++++++++ app/test/application/settings_page_test.dart | 116 ++++++++---------- .../settings_registration_test.dart | 7 +- .../tab_location_navigation_test.dart | 25 ++-- .../pipelines_settings_gear_test.dart | 73 +++++++++++ app/test/shell/navigation_rail_test.dart | 10 +- app/test/shell/settings_back_test.dart | 90 ++++++++++++++ 12 files changed, 353 insertions(+), 101 deletions(-) create mode 100644 app/notes/settings-destination-back.md create mode 100644 app/test/features/pipelines/pipelines_settings_gear_test.dart create mode 100644 app/test/shell/settings_back_test.dart diff --git a/app/lib/application/pipelines_app.dart b/app/lib/application/pipelines_app.dart index 93eef0c5..6606397f 100644 --- a/app/lib/application/pipelines_app.dart +++ b/app/lib/application/pipelines_app.dart @@ -706,6 +706,16 @@ class _PipelinesAppState extends State } void _selectDestination(AppDestination destination) { + // Settings is shown from its own nav item and has no Back, so its route + // (filed under the Pipelines tab) must not trap the Pipelines item: that + // item leaves Settings for the Pipelines body it showed before. + if (destination == AppDestination.pipelines && + _delegate.shellRoute.kind == AppRouteKind.settings) { + _delegate.goTo( + _bodyRoutes[AppDestination.pipelines] ?? AppRoute.pipelines, + ); + return; + } final last = _tabRoutes[destination]; _delegate.goTo(last ?? _routeOf(destination)); } diff --git a/app/lib/features/pipelines/screen.dart b/app/lib/features/pipelines/screen.dart index fb0ea904..55188ee9 100644 --- a/app/lib/features/pipelines/screen.dart +++ b/app/lib/features/pipelines/screen.dart @@ -2,7 +2,7 @@ import '../../ui/adaptive/segmented_bar.dart'; import '../../shell/destination.dart'; import '../../shell/detail_page.dart'; import '../../shell/list_detail.dart'; -import '../../shell/shell_rail_scope.dart'; +import '../../shell/navigation_rail.dart'; import 'package:flutter/material.dart'; import '../../core/api_gateway.dart'; @@ -289,9 +289,10 @@ class _PipelinesScreenState extends State { if (listShown && widget.onOpenSchedules != null) _schedulesButton(context), _refreshButton(context), - // A wide window's rail offers Settings; the gear stays on a phone. + // The phone's bar and the rail both offer Settings; the gear is only + // left where the floating tab bar (tabs only) is the shell's nav. if (listShown && - !ShellRailScope.isShown(context) && + showsFloatingTabBarOnly(context) && widget.onOpenSettings != null) _settingsButton(context), ], diff --git a/app/lib/shell/adaptive_shell.dart b/app/lib/shell/adaptive_shell.dart index 2230419a..505ed604 100644 --- a/app/lib/shell/adaptive_shell.dart +++ b/app/lib/shell/adaptive_shell.dart @@ -77,6 +77,11 @@ class _AdaptiveShellState extends State { late AppDestination _selected; final Set _visited = {}; final TabHistory _history = TabHistory(); + // The destination a shell control (rail, bar, floating bar) asked for and + // that is not shown yet. Settings reached this way is a destination; any + // other way in (a route, a deep link, the Pipelines gear) is a page to Back. + AppDestination? _navigatingTo; + bool _settingsPushed = false; // 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 = {}; @@ -100,6 +105,9 @@ class _AdaptiveShellState extends State { super.initState(); _bar.onNavigate = _select; _selected = widget.destination ?? AppDestination.pipelines; + // A first load that opens Settings (a deep link, a restored page) was not + // reached from a shell control, so its Back closes the page. + _settingsPushed = _selected == AppDestination.settings; _visited.add(_selected); HardwareKeyboard.instance.addHandler(_handleDestinationKeyEvent); } @@ -109,12 +117,23 @@ class _AdaptiveShellState extends State { super.didUpdateWidget(oldWidget); final destination = widget.destination; if (destination != null) { + if (destination != _selected) _noteShown(destination); _history.record(_selected, destination); _selected = destination; _visited.add(destination); } } + /// Records that [destination] is becoming the shown one. Settings opened by + /// a shell control is a destination (no Back); opened any other way it is a + /// page that Back closes. + void _noteShown(AppDestination destination) { + if (destination == AppDestination.settings) { + _settingsPushed = _navigatingTo != AppDestination.settings; + } + _navigatingTo = null; + } + /// The entry every tab control calls when tapped: a destination shown /// already is re-selected (see [AdaptiveShell.onDestinationReselected]), any /// other is selected. @@ -124,6 +143,13 @@ class _AdaptiveShellState extends State { reselected(destination); return; } + if (destination != _selected) { + _navigatingTo = destination; + // A selection the route never applies must not mark a later route. + WidgetsBinding.instance.addPostFrameCallback((_) { + if (mounted && _navigatingTo == destination) _navigatingTo = null; + }); + } _select(destination); } @@ -134,6 +160,7 @@ class _AdaptiveShellState extends State { return; } setState(() { + if (destination != _selected) _noteShown(destination); _history.record(_selected, destination); _selected = destination; _visited.add(destination); @@ -440,7 +467,9 @@ class _AdaptiveShellState extends State { String label, { required bool page, }) { - final onBack = spec?.onBack ?? (page ? _closePage : null); + // Settings reached from a shell control has no Back: it is a destination. + final onBack = + spec?.onBack ?? (page && _settingsPushed ? _closePage : null); final published = spec?.actions ?? const []; final onSearch = widget.onSearch; return SegmentedBar( diff --git a/app/lib/shell/destination.dart b/app/lib/shell/destination.dart index 9fe91835..523b28fc 100644 --- a/app/lib/shell/destination.dart +++ b/app/lib/shell/destination.dart @@ -2,10 +2,11 @@ import 'package:flutter/material.dart'; enum AppDestination { pipelines, runs, chat, search, settings } -/// The destinations the shell's tab bar (or, on a wide window, its rail) offers, +/// The tabs the shell's floating tab bar (or, on a wide window, its rail) offers, /// in order. Settings is a destination the shell can show (its route is -/// `/settings`), but it opens as a page, from the rail's foot on a wide window -/// or the Pipelines bar's gear on a phone, instead of being a tab. +/// `/settings`) and the rail and phone bar offer it too; it is a page of the +/// Pipelines tab, not a tab. Only the floating bar's width leaves Settings to +/// the Pipelines bar's gear. const List shellTabDestinations = [ AppDestination.pipelines, AppDestination.runs, diff --git a/app/lib/shell/navigation_rail.dart b/app/lib/shell/navigation_rail.dart index 93f6deec..7de8cf75 100644 --- a/app/lib/shell/navigation_rail.dart +++ b/app/lib/shell/navigation_rail.dart @@ -22,6 +22,12 @@ const double kNavigationRailMinWindowWidth = bool showsNavigationRail(BuildContext context) => MediaQuery.sizeOf(context).width >= kNavigationRailMinWindowWidth; +/// Whether the window shows the floating tab bar alone: wide enough for a list +/// beside an open item, too narrow for the rail. That bar lists the tabs only, +/// so there Settings is reached from the Pipelines bar's gear. +bool showsFloatingTabBarOnly(BuildContext context) => + showsListBesideDetail(context) && !showsNavigationRail(context); + /// The wide layout's left-edge navigation: a Material [NavigationRail] with /// an icon and a label per tab, the selected tab marked by the rail's /// indicator, and Settings pinned to its bottom. diff --git a/app/notes/settings-destination-back.md b/app/notes/settings-destination-back.md new file mode 100644 index 00000000..091c3ceb --- /dev/null +++ b/app/notes/settings-destination-back.md @@ -0,0 +1,72 @@ +# Settings destination: Back only when pushed; one Settings entry per screen + +Run 20261112-1022 (stage 01-implement). Not committed. + +## Rule + +- Settings opened from a shell control (rail item, phone bar item) is a + destination: no Back arrow. The Pipelines item leaves it for the Pipelines body. +- Settings opened any other way (a first load / deep link to `/settings`, a route + change that is not a shell control, the Pipelines gear) is a pushed page: Back + returns to Pipelines. +- The Pipelines bar's gear is kept only where the floating tab bar is the shell's + sole navigation (window width at least 600 and below the rail's 697; see + `showsFloatingTabBarOnly`). There the floating bar lists tabs only, so the gear + is the one Settings entry. The phone bar and the rail both offer Settings, so the + gear is gone there. + +## Changed paths (app/) + +- `lib/shell/adaptive_shell.dart`: `_navigatingTo` / `_settingsPushed`; `_noteShown` + is called on a shown-destination change; Back is built only when Settings is + pushed. +- `lib/shell/navigation_rail.dart`: `showsFloatingTabBarOnly(context)`. +- `lib/shell/destination.dart`: doc comment only. +- `lib/features/pipelines/screen.dart`: the bar's gear is shown only when + `showsFloatingTabBarOnly`; the rail check is gone. The non-shell paths keep the gear. +- `lib/application/pipelines_app.dart`: `_selectDestination` leaves Settings for the + Pipelines body (`_bodyRoutes`) instead of re-selecting the Settings route filed + under the Pipelines tab (the nav-only Settings has no Back, so without this the + Pipelines item would trap the user on Settings). +- Tests, new: `test/shell/settings_back_test.dart` (nav selection has no Back; route + push has Back and returns; first load has Back; nav after pushed clears Back); + `test/features/pipelines/pipelines_settings_gear_test.dart` (phone and rail: no + gear; floating band: gear present and its handler opens Settings). +- Tests, changed: `test/application/settings_page_test.dart`, + `test/application/tab_location_navigation_test.dart`, + `test/application/settings_registration_test.dart`, + `test/shell/navigation_rail_test.dart`. They now tap the nav item instead of the gear + and expect no Back on nav-opened Settings. + +## Focused results (memwatch, from app/) + +- New shell + gear tests and shell/rail/bar files: 54 passed, 0 failed. + (`settings_back_test`, `pipelines_settings_gear_test`, `navigation_rail_test`, + `shell_bar_test`, `tab_history_back_test`, `shell_navigation_bar_test`, + `split_destination_bar_test`, `pipelines_screen_filter_test`) +- Final run over all affected files (12 paths): 60 passed, 7 failed. The 7 are all + app-level tests that fail on HEAD for the same reason (see below). None is new. + - `settings_page_test`: "390 ... no gear ..." and "1200 ... rail ..." + - `tab_location_navigation_test`: "Settings is retained ...", "a delayed read ...", + "an explicit root URL ...", "Settings does not clear ..." + - `settings_registration_test`: "Settings shares socket and one native bar" +- Baseline check: a copy of app/ with HEAD's versions of the edited files fails the + same tests in the same way (`Expected: '/settings' Actual: '/pipelines'` after a + nav tap, and `Found 0 widgets with key 'segmented.more'` for the gear at 390). + `templates_wiring_test` passes on both. +- `tool/analyze.sh`: clean (0 errors, 0 warnings, 0 infos). + +## Limitations + +- App-level Settings navigation is not verified by these tests: a tap on the Settings + nav item does not change the route in this harness, on HEAD or on this change. The + behaviour is covered at shell level (`settings_back_test`) and by the gear test. +- System Back on a nav-opened Settings still closes to Pipelines (the shell's + PopScope is unchanged). +- The mid-width band keeps the gear by design (the floating bar has no Settings + entry). Adding Settings to the floating bar would remove it; not done here. +- Not built or captured here (ui-review owns that). States to re-capture: + - `base-light-430x900/12-settings.png` and `circle/01-hover.png`: Settings from the + nav has no Back arrow. + - `base-light-430x900/01-pipelines.png`: no Settings gear in the Pipelines header. + - A width between 600 and 696: the gear stays, and it opens Settings with Back. diff --git a/app/test/application/settings_page_test.dart b/app/test/application/settings_page_test.dart index 1b03f83e..da8c844b 100644 --- a/app/test/application/settings_page_test.dart +++ b/app/test/application/settings_page_test.dart @@ -7,15 +7,16 @@ import 'package:pipelines_app/features/settings/settings_screen.dart'; import 'package:pipelines_app/ui/adaptive/floating_destination_bar.dart'; import 'package:shared_preferences/shared_preferences.dart'; -import '../bar_action.dart'; import '../core/transport/pipelines_client_test.dart' show FakeChannel; import '../features/pipelines/fixtures.dart'; import 'pipelines_app_test.dart' show webServer; import 'pipelines_replies.dart'; -/// Settings is not a tab: it opens as a page (from the gear in the Pipelines -/// bar on a phone, from the rail's foot on a wide window), keeps its -/// `/settings` route (and deep link), and closes back to Pipelines. The tab bar keeps Pipelines selected meanwhile. +/// Settings is a navigation destination: the phone's bar and the wide rail +/// offer it, and the floating tab bar's width (between the list-detail and rail +/// widths) keeps the Pipelines bar's gear. Settings reached from a nav control +/// has no Back; reached as a pushed page (the gear, the /settings deep link) it +/// has Back, which returns to Pipelines. void main() { Future pumpApp( WidgetTester tester, { @@ -50,61 +51,47 @@ void main() { int selectedTab(WidgetTester tester) => tester.widget(find.byType(NavigationBar)).selectedIndex; - // A phone's Pipelines bar keeps the gear; a wide window's rail offers - // Settings instead (see the wide test below). - for (final size in [const Size(390, 844)]) { - testWidgets('${size.width}: the Pipelines bar gear opens Settings ' - 'as a page and Back returns', (tester) async { - final provider = await pumpApp( - tester, - location: '/pipelines', - size: size, - ); - // Four tabs and Settings as the bar's last destination. - expect( - tester - .widget(find.byType(NavigationBar)) - .destinations - .map((item) => (item as NavigationDestination).label), - ['Pipelines', 'Runs', 'Chat', 'Search', 'Settings'], - ); - expect( - find.byKey(const ValueKey('shell.destination.settings')), - findsOneWidget, - ); - expect(find.byKey(const ValueKey('shell.back')), findsNothing); + testWidgets('390: the bar offers Settings and no gear; Settings from the bar ' + 'has no Back and the Pipelines item leaves it', (tester) async { + final provider = await pumpApp( + tester, + location: '/pipelines', + size: const Size(390, 844), + ); + // Four tabs and Settings as the bar's last destination. + expect( + tester + .widget(find.byType(NavigationBar)) + .destinations + .map((item) => (item as NavigationDestination).label), + ['Pipelines', 'Runs', 'Chat', 'Search', 'Settings'], + ); + expect(find.byKey(const Key('pipelines-open-settings')), findsNothing); + expect(find.byKey(const ValueKey('shell.back')), findsNothing); - await tapBarAction( - tester, - find.byKey(const Key('pipelines-open-settings')), - 'Settings', - ); - await tester.pump(); - await tester.pump(); - expect(provider.value.uri.path, '/settings'); - expect(find.byType(SettingsScreen), findsOneWidget); - expect(find.text('Quick switch animation'), findsOneWidget); - await openSettingsSection(tester, 'Connection'); - expect(find.text('Server URL'), findsOneWidget); - // A page of Pipelines: Back in its bar, Settings selected in the bar. - expect(find.byKey(const ValueKey('shell.back')), findsOneWidget); - expect(find.byKey(const ValueKey('shell.search')), findsNothing); - expect(selectedTab(tester), 4); - expect(tester.takeException(), isNull); + await tester.tap(find.byKey(const ValueKey('shell.destination.settings'))); + await tester.pumpAndSettle(); + expect(provider.value.uri.path, '/settings'); + expect(find.byType(SettingsScreen), findsOneWidget); + expect(find.text('Quick switch animation'), findsOneWidget); + await openSettingsSection(tester, 'Connection'); + expect(find.text('Server URL'), findsOneWidget); + // A destination: no Back, and Settings is the selected item of the bar. + expect(find.byKey(const ValueKey('shell.back')), findsNothing); + expect(find.byKey(const ValueKey('shell.search')), findsNothing); + expect(selectedTab(tester), 4); + expect(tester.takeException(), isNull); - await tester.tap(find.byKey(const ValueKey('shell.back'))); - await tester.pump(); - await tester.pump(); - expect(provider.value.uri.path, '/pipelines'); - expect(find.byKey(const Key('pipelines-open-settings')), findsWidgets); - expect(find.byKey(const ValueKey('shell.back')), findsNothing); - await tester.pumpWidget(const SizedBox.shrink()); - await tester.pump(); - }); - } + await tester.tap(find.byKey(const ValueKey('shell.destination.pipelines'))); + await tester.pumpAndSettle(); + expect(provider.value.uri.path, '/pipelines'); + expect(find.byKey(const ValueKey('shell.back')), findsNothing); + await tester.pumpWidget(const SizedBox.shrink()); + await tester.pump(); + }); testWidgets('1200: the rail offers Settings at its foot and no gear is ' - 'left in the Pipelines toolbar; Settings is a page and Back returns', ( + 'left in the Pipelines toolbar; Settings from the rail has no Back', ( tester, ) async { final provider = await pumpApp( @@ -129,21 +116,19 @@ void main() { } await tester.tap(find.byKey(const ValueKey('shell.destination.settings'))); - await tester.pump(); - await tester.pump(); + await tester.pumpAndSettle(); expect(provider.value.uri.path, '/settings'); expect(find.byType(SettingsScreen), findsOneWidget); - // Settings is a page of Pipelines: the rail marks Settings, not a tab. + // Settings is a destination: the rail marks Settings, not a tab. expect( tester.widget(find.byType(NavigationRail)).selectedIndex, isNull, ); - expect(find.byKey(const ValueKey('shell.back')), findsOneWidget); + expect(find.byKey(const ValueKey('shell.back')), findsNothing); expect(tester.takeException(), isNull); - await tester.tap(find.byKey(const ValueKey('shell.back'))); - await tester.pump(); - await tester.pump(); + await tester.tap(find.byKey(const ValueKey('shell.destination.pipelines'))); + await tester.pumpAndSettle(); expect(provider.value.uri.path, '/pipelines'); expect(find.byKey(const Key('pipelines-open-settings')), findsNothing); expect( @@ -154,8 +139,8 @@ void main() { await tester.pump(); }); - testWidgets('the /settings deep link opens the Settings page and ' - 'the system Back closes it to Pipelines', (tester) async { + testWidgets('the /settings deep link opens Settings as a pushed page with ' + 'Back, and the system Back closes it to Pipelines', (tester) async { final provider = await pumpApp( tester, location: '/settings', @@ -168,8 +153,7 @@ void main() { final handled = await tester.binding.handlePopRoute(); expect(handled, isTrue, reason: 'Back closes the page, not the app'); - await tester.pump(); - await tester.pump(); + await tester.pumpAndSettle(); expect(provider.value.uri.path, '/pipelines'); await tester.pumpWidget(const SizedBox.shrink()); await tester.pump(); diff --git a/app/test/application/settings_registration_test.dart b/app/test/application/settings_registration_test.dart index 18a0014a..acaca0db 100644 --- a/app/test/application/settings_registration_test.dart +++ b/app/test/application/settings_registration_test.dart @@ -7,7 +7,6 @@ import 'package:pipelines_app/application/pipelines_app.dart'; import 'package:pipelines_app/core/transport/pipelines_client.dart'; import 'package:shared_preferences/shared_preferences.dart'; -import '../bar_action.dart'; import '../core/transport/pipelines_client_test.dart' show FakeChannel; import '../features/pipelines/fixtures.dart'; import 'pipelines_app_test.dart' show webServer, requestOf; @@ -45,11 +44,7 @@ void main() { ); await replyPipelines(tester, channel, PipelineFixture()); - await tapBarAction( - tester, - find.byKey(const Key('pipelines-open-settings')), - 'Settings', - ); + await tester.tap(find.byKey(const ValueKey('shell.destination.settings'))); await tester.pump(); await tester.pump(); expect(provider.value.uri.path, '/settings'); diff --git a/app/test/application/tab_location_navigation_test.dart b/app/test/application/tab_location_navigation_test.dart index 55de9dbf..f462a993 100644 --- a/app/test/application/tab_location_navigation_test.dart +++ b/app/test/application/tab_location_navigation_test.dart @@ -11,7 +11,6 @@ import 'package:pipelines_app/features/settings/settings_screen.dart'; import 'package:pipelines_app/features/pipelines/screen.dart'; import 'package:pipelines_app/shell/destination.dart'; -import '../bar_action.dart'; import '../core/transport/pipelines_client_test.dart' show FakeChannel; import '../features/pipelines/fixtures.dart'; import 'pipelines_app_test.dart' show webServer; @@ -63,13 +62,10 @@ void main() { final app = await mount(tester); await replyPipelines(tester, app.channel, PipelineFixture()); await tester.pumpAndSettle(); - await tapBarAction( - tester, - find.byKey(const Key('pipelines-open-settings')), - 'Settings', - ); - await tester.pumpAndSettle(); + await tab(tester, 'settings'); expect(app.provider.value.uri.path, '/settings'); + // A destination opened from its nav item: no Back. + expect(find.byKey(const ValueKey('shell.back')), findsNothing); final settingsState = tester.state(find.byType(SettingsScreen)); await tab(tester, 'chat'); expect(app.provider.value.uri.path, '/chat'); @@ -77,19 +73,12 @@ void main() { expect(app.provider.value.uri.path, '/settings'); expect(tester.state(find.byType(SettingsScreen)), same(settingsState)); await tab(tester, 'pipelines'); - expect( - app.provider.value.uri.path, - '/settings', - reason: 'tab retap is not Back', - ); - await tester.tap(find.byKey(const ValueKey('shell.back'))); - await tester.pump(); - await tester.pump(const Duration(milliseconds: 500)); expect( app.provider.value.uri.path, '/pipelines', - reason: 'explicit Back still exits Settings', + reason: 'the Pipelines item leaves Settings for its list', ); + expect(find.byKey(const ValueKey('shell.back')), findsNothing); expect(tester.takeException(), isNull); }); testWidgets( @@ -191,8 +180,8 @@ void main() { await tab(tester, 'pipelines'); expect(app.provider.value.uri.path, '/settings'); expect(tester.widget(hidden).initialPipelineId, 1); - await tester.tap(find.byKey(const Key('shell.back'))); - await tester.pumpAndSettle(); + // Settings has no Back; the Pipelines item returns to the open pipeline. + await tab(tester, 'pipelines'); expect(app.provider.value.uri.path, '/pipelines/1'); expect(tester.state(find.byType(PipelinesScreen)), same(pipelineState)); expect( diff --git a/app/test/features/pipelines/pipelines_settings_gear_test.dart b/app/test/features/pipelines/pipelines_settings_gear_test.dart new file mode 100644 index 00000000..b0cff78a --- /dev/null +++ b/app/test/features/pipelines/pipelines_settings_gear_test.dart @@ -0,0 +1,73 @@ +import 'package:flutter/material.dart'; +import 'package:flutter_test/flutter_test.dart'; +import 'package:pipelines_app/features/pipelines/screen.dart'; +import 'package:pipelines_app/shell/adaptive_shell.dart'; +import 'package:pipelines_app/shell/destination.dart'; +import 'package:pipelines_app/ui/adaptive/floating_destination_bar.dart'; + +import 'fixtures.dart'; +import 'test_helpers.dart'; + +/// The Pipelines bar's Settings gear inside the shell: it is kept only where the +/// floating tab bar is the shell's sole navigation (between the list-detail and +/// rail widths), because only there Settings has no nav entry. Elsewhere the +/// phone's bar or the rail offers Settings, so the bar has no gear. +void main() { + // Returns how many times the gear opened Settings. + Future pumpInShell(WidgetTester tester, Size size) async { + tester.view.physicalSize = size; + tester.view.devicePixelRatio = 1; + addTearDown(tester.view.resetPhysicalSize); + addTearDown(tester.view.resetDevicePixelRatio); + var opened = 0; + final gateway = gatewayFor(PipelineFixture()); + await tester.pumpWidget( + MaterialApp( + home: AdaptiveShell( + destination: AppDestination.pipelines, + destinationBodies: { + // The app's Pipelines destination embeds the screen in the shell. + AppDestination.pipelines: (_) => PipelinesScreen( + gateway: gateway, + embedded: true, + onOpenSettings: () => opened++, + ), + }, + ), + ), + ); + await tester.pumpAndSettle(); + return () => opened; + } + + testWidgets('a phone bar offers Settings, so the Pipelines bar has no gear', ( + tester, + ) async { + await pumpInShell(tester, const Size(390, 844)); + expect(find.byType(NavigationBar), findsOneWidget); + expect(find.byKey(const Key('pipelines-open-settings')), findsNothing); + }); + + testWidgets('a rail offers Settings, so the Pipelines bar has no gear', ( + tester, + ) async { + await pumpInShell(tester, const Size(1200, 800)); + expect(find.byType(NavigationRail), findsOneWidget); + expect(find.byKey(const Key('pipelines-open-settings')), findsNothing); + }); + + testWidgets('the floating tab bar lists tabs only, so the Pipelines bar ' + 'keeps the gear and it opens Settings', (tester) async { + final opened = await pumpInShell(tester, const Size(650, 844)); + expect(find.byType(FloatingDestinationBar), findsOneWidget); + expect(find.byKey(const Key('pipelines-open-settings')), findsOneWidget); + // At this width the bar folds the gear into its More menu, so it is not + // hit-testable here; its handler is what opens Settings. + final gear = tester.widget( + find.byKey(const Key('pipelines-open-settings')), + ); + expect(gear.tooltip, 'Settings'); + gear.onPressed!(); + expect(opened(), 1); + }); +} diff --git a/app/test/shell/navigation_rail_test.dart b/app/test/shell/navigation_rail_test.dart index 16597aef..b4fb741a 100644 --- a/app/test/shell/navigation_rail_test.dart +++ b/app/test/shell/navigation_rail_test.dart @@ -90,8 +90,8 @@ void main() { expect(find.text('runs body'), findsOneWidget); }); - testWidgets('Settings opens from the rail foot as a page and no tab is ' - 'selected meanwhile', (tester) async { + testWidgets('Settings opens from the rail foot as a destination with no ' + 'Back and no tab is selected meanwhile', (tester) async { final semantics = tester.ensureSemantics(); await pumpShell(tester, width: 1000); @@ -106,8 +106,10 @@ void main() { .isSelected, Tristate.isTrue, ); - // The page's own Back returns to Pipelines, the tab it belongs to. - await tester.tap(find.byKey(const ValueKey('shell.back'))); + // Opened from its rail item, Settings is not a page: no Back. + expect(find.byKey(const ValueKey('shell.back')), findsNothing); + // The Pipelines item leaves it for the Pipelines tab. + await tester.tap(find.byKey(const ValueKey('shell.destination.pipelines'))); await tester.pumpAndSettle(); expect(tester.widget(rail()).selectedIndex, 0); semantics.dispose(); diff --git a/app/test/shell/settings_back_test.dart b/app/test/shell/settings_back_test.dart new file mode 100644 index 00000000..85cfb3d6 --- /dev/null +++ b/app/test/shell/settings_back_test.dart @@ -0,0 +1,90 @@ +import 'package:flutter/material.dart'; +import 'package:flutter_test/flutter_test.dart'; +import 'package:pipelines_app/shell/adaptive_shell.dart'; +import 'package:pipelines_app/shell/destination.dart'; + +/// Settings' Back: a destination reached from a shell control has none; a page +/// pushed by a route (a first load or a route change, such as a deep link or +/// the Pipelines gear) has one that returns to Pipelines. +void main() { + AdaptiveShell shellAt(AppDestination destination) => AdaptiveShell( + destination: destination, + destinationBodies: { + for (final value in AppDestination.values) + value: (_) => Text('${value.name} body'), + }, + ); + + Future pumpAt( + WidgetTester tester, + AppDestination destination, { + double width = 1000, + }) async { + tester.view.physicalSize = Size(width, 800); + tester.view.devicePixelRatio = 1; + addTearDown(tester.view.resetPhysicalSize); + addTearDown(tester.view.resetDevicePixelRatio); + await tester.pumpWidget(MaterialApp(home: shellAt(destination))); + await tester.pumpAndSettle(); + } + + testWidgets('Settings selected from a rail item has no Back', (tester) async { + await pumpAt(tester, AppDestination.pipelines); + expect(find.byKey(const ValueKey('shell.back')), findsNothing); + + await tester.tap(find.byKey(const ValueKey('shell.destination.settings'))); + await tester.pumpAndSettle(); + expect(find.text('settings body'), findsOneWidget); + expect(find.byKey(const ValueKey('shell.back')), findsNothing); + }); + + testWidgets('Settings selected from a phone bar item has no Back', ( + tester, + ) async { + await pumpAt(tester, AppDestination.pipelines, width: 390); + await tester.tap(find.byKey(const ValueKey('shell.destination.settings'))); + await tester.pumpAndSettle(); + expect(find.text('settings body'), findsOneWidget); + expect(find.byKey(const ValueKey('shell.back')), findsNothing); + }); + + testWidgets('Settings pushed by a route change has Back, which returns to ' + 'Pipelines', (tester) async { + await pumpAt(tester, AppDestination.pipelines); + // The route moves to Settings (as a gear or a deep link does). + await tester.pumpWidget( + MaterialApp(home: shellAt(AppDestination.settings)), + ); + await tester.pumpAndSettle(); + expect(find.text('settings body'), findsOneWidget); + expect(find.byKey(const ValueKey('shell.back')), findsOneWidget); + + await tester.tap(find.byKey(const ValueKey('shell.back'))); + await tester.pumpAndSettle(); + expect(find.text('pipelines body'), findsOneWidget); + expect(find.byKey(const ValueKey('shell.back')), findsNothing); + }); + + testWidgets('a first load on Settings (a deep link) has Back', ( + tester, + ) async { + await pumpAt(tester, AppDestination.settings); + expect(find.text('settings body'), findsOneWidget); + expect(find.byKey(const ValueKey('shell.back')), findsOneWidget); + }); + + testWidgets('a nav selection after a pushed Settings clears its Back', ( + tester, + ) async { + await pumpAt(tester, AppDestination.settings); + expect(find.byKey(const ValueKey('shell.back')), findsOneWidget); + await tester.tap(find.byKey(const ValueKey('shell.destination.chat'))); + await tester.pumpAndSettle(); + expect(find.text('chat body'), findsOneWidget); + + // Settings opened again from its rail item is a destination, not a page. + await tester.tap(find.byKey(const ValueKey('shell.destination.settings'))); + await tester.pumpAndSettle(); + expect(find.byKey(const ValueKey('shell.back')), findsNothing); + }); +}