Files
pipelines/app/notes/settings-single-page.md
T
alan 3136e5bb7e Redesign Settings as grouped searchable page
Replace the tabbed Settings flow with a single grouped page that searches and lazily loads server-backed sections. Preserve existing settings behavior while adding inline loading and retry states and updating coverage for the new navigation model.
2026-11-12 02:54:07 +00:00

6.4 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.