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.
This commit is contained in:
2026-11-12 02:54:07 +00:00
parent 9bb87e5118
commit 3136e5bb7e
29 changed files with 1467 additions and 777 deletions
+98
View File
@@ -0,0 +1,98 @@
# 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.