Files
pipelines/app/notes/S1b.md
T

168 lines
9.9 KiB
Markdown

# S1b — saved-schedules list (read-only)
## What changed
App-only files; no existing feature, shell, `main`, pubspec, data/domain or
server source edited.
| File | Lines | Responsibility |
| --- | --- | --- |
| `lib/features/schedules/screen.dart` | 94 | `SchedulesScreen(gateway, onOpen, pipelineId)` body; owns controller, search text and scroll |
| `lib/features/schedules/ui/list/schedule_list_controller.dart` | 168 | list load, newest-only publish, search/enabled filter, failure classification, cached visible view |
| `lib/features/schedules/ui/list/schedule_list_view.dart` | 188 | adaptive list, loading/empty/error states, stable error-banner slot |
| `lib/features/schedules/ui/list/schedule_list_toolbar.dart` | 179 | native search, all/enabled filter, refresh, count |
| `lib/features/schedules/ui/list/schedule_list_row.dart` | 115 | tappable row with server fields |
| `lib/features/schedules/ui/list/schedule_list_format.dart` | 70 | honest value/date/count wording |
| `test/features/schedules/ui/list/schedules_screen_test.dart` | 171 | search, filter, empty-filter wording, onOpen, states, unsubscribe |
| `test/features/schedules/ui/list/schedules_refresh_test.dart` | 119 | query/scroll preservation across successful and failed refresh |
| `test/features/schedules/ui/list/schedules_layout_test.dart` | 79 | Material + Cupertino at 390px, 1x and 2x text |
| `test/features/schedules/ui/list/schedule_list_controller_test.dart` | 182 | envelopes, empty/unsupported/error wording, ordering, dispose |
| `test/features/schedules/ui/list/schedule_list_filter_test.dart` | 87 | search/filter behavior and cache invalidation |
| `test/features/schedules/ui/list/schedule_list_format_test.dart` | 72 | complete/missing/invalid values and fixed due-time wording |
| `test/features/schedules/ui/list/schedule_list_test_support.dart` | 143 | recorded/immediate and controlled fake gateways |
| `test/features/schedules/ui/list/schedule_screen_harness.dart` | 33 | 390px test app builder |
| `tool/schedules_list_probe_app.dart` | 110 | local-only browser fixture (fake schedules, light/dark) |
| `tool/schedules_list_probe.mjs` | 252 | real Chrome probe, content assertions, five captures |
## Behavior
`SchedulesRepository.listSchedules` and `SavedSchedule` are reused unchanged.
The screen calls only `list_schedules`, with `pipeline_id` when supplied. There
is no add/edit/delete/pause/enable control and no other request type.
- A valid empty reply shows `No schedules yet.` An older/unsupported envelope is
a distinct error (`This server does not support saved schedules…`), and a
transport/repository error keeps its actual text. A failed refresh with rows
already loaded keeps those rows and shows the error above them.
- Older-server detection now matches the web client's wording
(`unknown (message|request|command)` and `unsupported…schedule`, case
insensitive) in addition to the repository's `no schedules response` report,
so a real server refusal receives the same upgrade guidance as the web.
- Search matches schedule name, prompt and the actual pipeline ID (`Pipeline 4`,
including a bare `4`). No pipeline name exists in the saved-schedule record, so
matching names is not possible without another request; none is faked.
- Filter is `All` / `Enabled`. Paused rows remain visible under `All`. When the
search box is empty and only the filter hides every row, the empty state says
`No enabled schedules.`; an entered query still says
`No schedules match this search.`
- Rows show the server's pipeline ID, pinned version, workspace, timer rule,
timezone and `next_due`. Missing values stay `Pipeline unavailable`,
`Version unavailable`, `Workspace unavailable`, `Timer unavailable`; an
omitted/`Local` timezone is `Server timezone`; an absent/invalid due time is
`Not scheduled` / `Next time unavailable`; a paused row shows `Paused`.
Due values are converted to local time and labelled `(your local time)`,
matching the web client's wording.
- Selecting a row passes the exact `SavedSchedule` object from the loaded list to
`onOpen`; it does not re-fetch, copy into a draft or mutate it.
- Query, filter and list are not recreated by refresh, so the search text and
`ScrollController` offset survive. The failed-refresh banner occupies a
permanently present slot above the list, so showing or clearing it does not
change the list's ancestor chain or rebuild its `Scrollable`. Only the newest
refresh generation may publish; stale replies and replies after dispose are
ignored.
- The filtered view is cached in the controller and invalidated on query,
filter and new replies, so one rebuild does not repeat the same O(n) pass for
the body, count and toolbar.
Controls are native defaults: Material `TextField`, `SegmentedButton`,
`IconButton`, `TextButton`, `Divider`, `CircularProgressIndicator`; Cupertino
`CupertinoSearchTextField`, `CupertinoSlidingSegmentedControl`,
`CupertinoButton`, `CupertinoActivityIndicator`. No CSS palette, custom font,
fixed row height or bespoke control was added. Layout is a content-driven column
with wrapping text; a single max-width constraint keeps the filter compact on
wide screens.
## Review findings addressed
- **M1 (must-fix), failed refresh reset the scroll offset.** Reproduced with the
new `schedules_refresh_test.dart` against the previous structure: the test
failed because the `Expanded` child changed from `ListView` to
`Column(banner, Expanded(ListView))`, recreating the `Scrollable`. With the
permanent banner slot the test passes for both the failure transition and the
later recovery/retry, at the unchanged offset. The test was also run against a
temporary local revert of the fix and failed as expected, then restored.
- **Advisory 1**, filter-only empty state: now `No enabled schedules.` unless a
query is active.
- **Advisory 2**, older-server wording: web-parity regex added and tested with
raw `unknown request`, `UNKNOWN COMMAND` and `Unsupported schedules command`
errors; unrelated errors keep their exact text.
- **Advisory 5**, repeated filtering: visible list cached and invalidated.
- **Advisory 6**, test oracle: the layout test now asserts the literal
`Next due: 2026-10-22 09:00 (your local time)` from a zone-less fixture instant;
the duplicated formatter helper was removed from the harness.
- **Advisory 7**, Material dark evidence: the fixture accepts
`?brightness=dark` and the probe captures Material dark at 390px.
Advisory 3 (typed repository reason instead of matching a private message
string) needs a change in the landed `data/schedules_repository.dart`, outside
this list slice; the exact-string mapping is retained and documented. Advisory
4 (formatting in the rule's IANA timezone) still needs a timezone package.
## Checks actually run
```
dart format --set-exit-if-changed lib/features/schedules \
test/features/schedules/ui/list tool/schedules_list_probe_app.dart
# 19 files, 0 changed
flutter test test/features/schedules/ui/list # 29 passed
flutter test # 110 passed
flutter analyze # No issues found!
flutter build web # ✓ Built build/web
flutter build web -t tool/schedules_list_probe_app.dart # ✓ Built build/web
node --check tool/schedules_list_probe.mjs # clean
node tool/schedules_list_probe.mjs --out …/public/s1b-schedules-captures
# 5 captures, content assertions passed
```
The focused suite covers the list envelope (with and without `pipeline_id`),
empty vs unsupported vs transport errors, older-server wording, a failed refresh
retaining rows, out-of-order refresh, disposal safety, search/filter behavior and
cache invalidation, `onOpen` receiving the exact raw record, no mutation calls,
query preservation, a successful and a failed refresh preserving scroll (plus
recovery), filter-only empty wording, both MaterialApp and CupertinoApp at 390px
with 1x and 2x text, and no render overflow.
## Browser evidence
Real headless Chrome served the fixture build on an OS-assigned loopback port,
with explicit MIME types, Flutter semantics enabled, and content assertions
before each capture:
- `/Users/alan/.local/share/pipelines/data/artifacts/58/public/s1b-schedules-captures/s1b-schedules-material-390.png`
- `…/s1b-schedules-material-390-2x.png`
- `…/s1b-schedules-material-390-dark.png`
- `…/s1b-schedules-cupertino-390.png` (platform dark appearance)
- `…/s1b-schedules-material-1100.png`
- `…/manifest.json`
The fixture uses a local fake gateway with four records (enabled, paused, clock
rule, sparse record). It never contacted a Pipelines server, bypassed
authentication or created/changed a real schedule or run.
## Full diff
Every changed path is new and untracked; no pre-existing work was modified,
reset or deleted. The complete patch is saved at:
`/Users/alan/.local/share/pipelines/data/artifacts/58/public/s1b-schedules-list.diff`
## Honest limits
- **Not committed.** This stage forbids commit/push/deploy, so the candidate
remains uncommitted in the `flutter/s1-list` worktree for the manager.
- **Not wired into the shell.** `lib/main.dart`, `lib/shell/` and destination
registration are untouched; the Schedules destination still shows its
placeholder until the separate integration item.
- **No schedule editor.** Create/edit/delete/pause remain separate follow-up
items; no mutation was implemented or exercised.
- **Pipeline-name search unavailable.** The saved-schedule record exposes only
`pipeline_id`; search uses that exact ID rather than inventing a name.
- **Due times use the device timezone.** The absolute `next_due` instant is shown
as `(your local time)` and the rule timezone separately. The web client can
format in the rule's IANA timezone; that needs a timezone package not available
in this slice.
- **Mobile unverified.** No Android/iOS build, emulator, ADB or device was used.
- **Live server unverified.** Browser evidence is fixture-only by design; no
production authentication or schedule data was used.