Files
pipelines/app/notes/settings-destination-back.md
T
alan 26bb583f10 Refine Settings destination shell integration
Keep Settings navigation independent while preserving shell actions and destination-specific state. Add the reviewed chat, run-entry, layout, and regression-test updates needed by the destination behavior.
2026-11-12 11:21:26 +00:00

4.2 KiB

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.