Files
pipelines/app/notes/settings-single-page.md
T
alan a73eb960b9 Keep settings and delivery updates together
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.
2026-11-12 03:27:37 +00:00

10 KiB
Raw Blame History

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, then notification_settings on 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.dart stays deleted. Its main-side change added a walkthrough row to the old tab layout; this page already has the row.
  • settings_keys.dart keeps SettingsKeys.showWalkthrough only; main's SettingsKeys.walkthrough is dropped.
  • settings_screen.dart keeps this branch's imports; main's settings_walkthrough_section.dart import is dropped.
  • settings_walkthrough_section.dart and its test test/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 in settings_screen_test.dart.
  • pipelines_app.dart now passes onShowWalkthrough to Settings, calling showFirstRunWalkthrough(context). Before this, the row was disabled in the app because nothing supplied the handler. The settings route builder now names its parameter context.
  • 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) and test/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 the pipelines-open-settings gear. Not fixed here; these tests need a decision on the gear.
  • settings_tabs_test.dart and settings_topic_restore_test.dart do 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) and settings_registration_test.dart. They fail at a tap on segmented.more and a route check before reaching this layout. Not changed here.
  • tool/analyze.sh on 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.