Preserve the reviewed grouped Settings page while fixing its embedded phone safe area, and land the accompanying notification, walkthrough, terminal, and documentation updates captured by this run.
10 KiB
settings-single-page — Settings as one searchable, grouped page
What changed
Settings is one scrolling page of Material sections instead of five tabs. A pinned search field filters sections by title and keywords and jumps to the first match. On a wide body (≥ 840 px) a slim jump index sits beside the list. The content column is 720 px, centred beside the index.
Server-backed sections load lazily: a section renders a skeleton until the list scrolls within one viewport of it, or a search matches it. Once reached it stays mounted and keeps its last value.
| File | Lines | Responsibility |
|---|---|---|
lib/features/settings/settings_section.dart |
44 | Section model: id, title, keywords, lazy, builder, query match |
lib/features/settings/settings_search_page.dart |
226 | The page: pinned search, lazy activation, jump, index beside on wide |
lib/features/settings/settings_page_chrome.dart |
79 | Search field and the jump index widget |
lib/features/settings/settings_page_sections.dart |
213 | The ordered section list (part of settings_screen.dart) |
lib/features/settings/settings_screen.dart |
191 | Builds the page; navigationScope parameter removed |
lib/features/settings/settings_server_load.dart |
66 | ServerLoad<T>: one in-flight load, cached last value, refresh |
lib/features/settings/settings_server_view.dart |
138 | Skeleton / cached value / inline error with Retry; starts its load on mount |
lib/features/settings/settings_skeleton.dart |
19 | Group-shaped placeholder for a not-yet-reached lazy section |
lib/features/settings/settings_layout.dart |
+17 | Index width and breakpoint, preload distance, endpoint debounce |
lib/features/settings/security/settings_security_section.dart |
172 | ServerLoad + inline Retry; endpoint reload debounced 600 ms (was per keystroke) |
lib/features/settings/ntfy_settings_controller.dart |
+6 | loadFailed flag |
lib/features/settings/settings_ntfy_section.dart |
+6 | Retry also after a failed refresh with cached values |
lib/application/pipelines_app.dart |
−1 | Drops the navigationScope argument |
Removed: settings_tabs.dart, settings_topic_pages.dart, settings_topic_store.dart
(the remembered-category store), and their tests settings_tabs_test.dart and
settings_topic_restore_test.dart. SettingsPageBody is unchanged (health and
storage screens still use it).
Server loads found
- Sign-in security fetched on mount and again on every keystroke of the URL draft (its endpoint followed the draft). Now one load per endpoint, debounced.
- Sign-in security caught only
SessionSecurityException; any other failure left the section silent. Now every failure shows inline with Retry. - Phone notifications (ntfy) loaded on mount of the category. Now lazy.
- Health and storage are navigation rows; they fetch only when opened. Unchanged.
- No sequential server awaits on the page's load path were found.
Help and about
The group Help and about (section id help, settings_page_sections.dart) holds
the keyboard shortcuts row and a "Show the walkthrough" row (SettingsKeys.showWalkthrough).
The walkthrough itself is not in this codebase yet (the parallel run adds it), so the
row takes an optional SettingsScreen.onShowWalkthrough callback. Without a callback
the row is present but disabled. The parallel run wires the callback in pipelines_app.dart
or the shell; this stage did not add a walkthrough action.
Focused results
Command (from app/):
tool/memwatch/full.sh 'test/features/settings/settings_server_load_test.dart test/features/settings/settings_search_page_test.dart test/features/settings/settings_screen_test.dart test/features/settings/settings_layout_test.dart test/features/settings/settings_library_test.dart test/features/settings/settings_shell_background_test.dart test/features/settings/settings_initial_connection_test.dart test/features/settings/settings_ntfy_section_test.dart test/features/settings/security/settings_security_section_test.dart test/application/settings_page_test.dart test/application/settings_registration_test.dart'
Result: PASS, 51 passed, 0 failed, 0 skipped (memwatch verdict names only these paths).
An earlier run of the same list had 2 failures in the new walkthrough tests (a
type cast on the SettingsRow key instead of its ListTile); fixed, then passed.
tool/analyze.sh on the settings lib/test paths and the two application tests: clean.
New coverage:
settings_server_load_test.dart: concurrent loads share one request; a failed refresh keeps the cached value and a retry clears the error; a reply after dispose is dropped.settings_search_page_test.dart: local sections render while a server section has not answered (no request until reached); search filters by title and keywords with all words required; a search that matches a lazy section loads it; a failing server section shows its own Retry while other sections stay; the jump index shows at 1200 px and not at 390 px.settings_screen_test.dart: Help and about keeps the shortcuts row and is searchable; "Show the walkthrough" row is enabled and calls its callback when a callback is given, is disabled without one, and is reachable by search ("walkthrough").settings_layout_test.dart: centred 720 px column beside the index; narrow fills the inset; the search field is pinned under the bar.
Expectation changes (behaviour the task asked for, not new behaviour):
- Tab-selection helper became
openSettingsSection(tester, title), which scrolls to a heading. - URL and workspace fields are addressed by key, because the search field is now the first text field.
- The ping test now asserts the request order (
ping, thennotification_settingson a tall window), since the ntfy section is near the top there.
Affected states (not captured here)
Phone and desktop, light and dark: no build or capture was run in this stage; ui-review owns those. States to capture: default page; search with matches; search with no match; index on wide; a lazy section as skeleton and loaded; a server section with error and Retry.
Limitations
- Search matches whole sections (title and keywords), not individual rows.
- Lazy activation is by viewport distance; a long window loads ntfy and security on open.
- Not on-device verified.
- The "Check for updates" action walks the servers sequentially when pressed. That is a user action, not the page load, and was left unchanged.
Re-entry after land: main moved (merge of main)
Main changed the Settings files this branch rewrote, so the merge conflicted in
settings_keys.dart, settings_screen.dart and settings_topic_pages.dart.
Resolution (merge staged, not committed):
settings_topic_pages.dartstays deleted. Its main-side change added a walkthrough row to the old tab layout; this page already has the row.settings_keys.dartkeepsSettingsKeys.showWalkthroughonly; main'sSettingsKeys.walkthroughis dropped.settings_screen.dartkeeps this branch's imports; main'ssettings_walkthrough_section.dartimport is dropped.settings_walkthrough_section.dartand its testtest/features/settings/settings_walkthrough_test.dart(main's, for the removed tab row) are deleted. The reopen behaviour stays covered by the Help and about row test insettings_screen_test.dart.pipelines_app.dartnow passesonShowWalkthroughto Settings, callingshowFirstRunWalkthrough(context). Before this, the row was disabled in the app because nothing supplied the handler. The settings route builder now names its parametercontext.- Main's device-delivery changes (warning, connection log,
open()) merged cleanly and are kept.
Focused results (memwatch, from app/):
- Passing: settings_screen_test, settings_device_delivery_section_test, settings_search_page_test, settings_layout_test, settings_library_test, settings_server_load_test, first_run_walkthrough_test, walkthrough_gate_test.
- Failing:
test/application/settings_page_test.dart(2 tests: the bar gear case and the rail case) andtest/application/settings_registration_test.dart(1 test). The same tests fail on untouched main, and the pre-merge branch commit passes them. Likely cause: main's Pipelines bar now includes the terminal toggle (pipelines_app.dart_shellFor), which pushes out thepipelines-open-settingsgear. Not fixed here; these tests need a decision on the gear. settings_tabs_test.dartandsettings_topic_restore_test.dartdo not exist on this branch; they are stale names in the change list.
tool/analyze.sh: clean.
Not on-device verified; no UI captured in this stage.
Re-entry after ui-review: phone bar over the page
ui-review (visit 2) captured the phone page panned under the shell's floating tab bar. The bar's glass let the Terminal help text and its controls show through the bar, so they could not be read.
Cause: the shell's Scaffold uses extendBody, so the page's body reads the bar's
height as its bottom padding. The page padded only its scroll end, so rows scrolled
under the bar.
Fix (settings_screen.dart, embedded branch): the page's viewport now ends at the
bar's top edge. It reserves the body's bottom padding (the bar's height, or the
system inset when no bar shows) and removes that padding from its subtree, so the
page's own end padding is not counted twice. The non-embedded (own Scaffold) branch
is unchanged. On a wide window the bar is in the rail, so the reserved space is zero.
New regression test: settings_screen_test.dart, "phone: the page scrolls to rest
above the floating tab bar". It pumps the page in a Scaffold(extendBody: true) with
an 80 px bottom bar at 390×844, scrolls to the end, and asserts the list viewport and
the last row (the walkthrough row) end above the bar. It was confirmed to fail on the
previous embedded layout and to pass with this fix.
Focused results (memwatch, from app/, same path list as above, plus the new test):
- 49 passed, 3 failed. The 3 failures are the known application tests from the
land stage:
settings_page_test.dart(390 and 1200 cases) andsettings_registration_test.dart. They fail at a tap onsegmented.moreand a route check before reaching this layout. Not changed here. tool/analyze.shon the settings lib/test paths and the two application tests: clean.
Affected states to re-capture (ui-review owns this): phone light and dark, panned to the end of the page (the walkthrough row and Terminal help text must sit above the bar); desktop, where the bar is in the rail and nothing changes. Not on-device verified; no UI was built or captured in this stage.