a73eb960b9
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.
173 lines
10 KiB
Markdown
173 lines
10 KiB
Markdown
# 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.
|