Files
pipelines/app/notes/S1-form.md
T

197 lines
11 KiB
Markdown

# S1-form — native saved-schedule form
Manager acceptance: merged after inspecting the new-source-only diff. Re-ran all
schedule tests and rebuilt the fixture; the probe passed every step and produced
seven captures. Inspected the Cupertino dark phone form and the 320px/2x Material
form: full wrapping labels, native fields/menus/switches, readable semantic error
colour, no clipped helper copy. The form mutates only the caller-owned draft and
calls the injected submit callback, so no repository/route/scheduler is implied.
Schedule persistence, pause/delete, conflicts and the Schedule-this-run seed are
still separate wiring work; nothing was saved to a real server.
## What changed
New files only. No existing feature, shell, route, `main`, pubspec, server, `web/`,
Android/iOS or deployment source was edited.
| File | Lines | Responsibility |
| --- | ---: | --- |
| `lib/features/schedules/ui/editor/schedule_editor_form.dart` | 234 | state/controllers, submit/validation/refusal, native Cancel/Save actions |
| `lib/features/schedules/ui/editor/schedule_editor_form_body.dart` | 229 | visible column: heading, note, native fields, live error slot |
| `lib/features/schedules/ui/editor/schedule_editor_fields.dart` | 191 | wrapping label shell, native text field/switch, host secondary/error styles |
| `lib/features/schedules/ui/editor/schedule_editor_selectors.dart` | 200 | native timer/notification menus and weekday checkboxes |
| `lib/features/schedules/ui/editor/schedule_editor_wording.dart` | 45 | verbatim browser copy and stable keys |
| `test/features/schedules/ui/editor/schedule_editor_form_test.dart` | 162 | invalid/create/clock/edit record tests |
| `test/features/schedules/ui/editor/schedule_editor_interaction_test.dart` | 164 | refusal, duplicate submit, Cupertino fields/switch/day, Cancel |
| `test/features/schedules/ui/editor/schedule_editor_layout_test.dart` | 80 | 320px/2x wrapping and native dark Cupertino |
| `test/features/schedules/ui/editor/schedule_editor_harness.dart` | 82 | 390/320 Material and Cupertino hosts |
| `tool/schedule_editor_probe_app.dart` | 170 | standalone local fixture with refusing/accepted fake callback |
| `tool/schedule_editor_probe.mjs` | 368 | real Chrome interaction and seven captures |
The original aim was two production files. The landing draft, the form state, the
native control primitives, the selectors and the verbatim copy do not fit under
the working agreement's 250-line aim together, so they are split by
responsibility rather than into arbitrary fragments. No generic form framework,
inherited controller or schema was introduced; every file is specific to saved
schedules.
## Behavior
`ScheduleEditorForm` binds the landed `ScheduleDraft` and nothing else. It opens
with the draft's current values and mutates only the editable fields on submit.
It then calls `draft.build()`:
- invalid draft — the returned field errors are shown under their controls and
the injected callback is **not** called; there is no partial record;
- valid draft — every control is disabled, Save reads `Saving…`, and
`onSubmit(record)` receives the exact non-null `build()` record once;
- async refusal — controls re-enable, typed controller values stay verbatim,
and the form shows `"<server reason> Your draft is preserved. If this schedule
changed elsewhere, reopen it before retrying."` (a blank reason gets `The
schedule was not saved.`). The line is a live-region semantics node, so it is
announced like the browser's `role="alert"`; the browser probe asserts its
visible text after scrolling to it.
After an accepted callback the form re-enables; the integrating caller owns
closing/replacing it, exactly as the web editor closes its modal on success. No
close/route/save logic exists in this slice.
The form reads its draft once, in `initState` (the Material selectors also take
an `initialValue`). A caller that reuses the widget with a different draft must
give it a new key, e.g. by operation or `draft.id`, so the controls reinitialise;
mutating the draft in place without a new key is not reflected in the UI.
Editable in this slice: name, prompt, pinned version, absolute server workspace,
timer mode, interval, clock times, weekdays, timezone, enabled and notification
mode. `draft.source`/`pipelineId` are not editable here. The advanced run options
(`model`, `stage_models`, other input keys, `write_paths`, `allow_tools`, `title`,
`output_format`) are not rendered and are **preserved exactly** because the
landed draft starts every edit from the server snapshot. A create still emits the
web sentinel `id: 0`; an edit keeps its exact `id` and `revision`.
Weekday toggles send one day key per interaction and the form applies them in
server weekday order, so two quick taps cannot lose the first selection. A raw
notification value outside `auto|on|off` stays visible/selectable and is then
rejected by the draft's validation rather than crashing a dropdown assertion.
## Native presentation
- Labels are wrapping text above each control, matching the browser's sibling
label word and avoiding a floating-label ellipsis at 2x text. Helper text and
field errors wrap below the control; no fixed control/row heights.
- Material: `TextField`, `Switch`, `Checkbox`, `DropdownButtonFormField`,
`TextButton`, `FilledButton`.
- Cupertino: `CupertinoTextField`, `CupertinoSwitch`, `CupertinoCheckbox`,
`CupertinoButton` menuing through `CupertinoActionSheet`, plus the same
`CupertinoButton` actions.
- Typography and colours come from `Theme`/`CupertinoTheme` semantic roles and
dynamic label/secondary/error colours. Material helpers use `bodySmall`; the
Cupertino secondary style stays on the theme's text style at the native 14pt
detail size and is still scaled by the text scaler. No bespoke palette or
control clone was added.
- The dark Cupertino fixture is a real `CupertinoApp` with
`CupertinoThemeData(brightness: dark)`; its base page background is the native
`systemBackground` black, while fields, labels, blue actions and the green
switch resolve from the dark Cupertino roles. The widget test also asserts the
dark brightness, dark label colour and that no Material control is present.
## Browser fixture
`tool/schedule_editor_probe_app.dart` is standalone: an in-process
`ScheduleDraft.create` (pipeline 4, version 2, `/srv/research`,
`Europe/London`) and a fake `onSubmit`. The first valid submit is refused after
900 ms; the retry is accepted. The state is published at
`globalThis.scheduleEditorProbe`; the accepted record is rendered on the page.
No socket, server, authentication or real schedule is involved.
## Checks actually run
```
dart format lib/features/schedules/ui/editor test/features/schedules/ui/editor \
tool/schedule_editor_probe_app.dart # clean
flutter analyze # No issues found!
flutter test test/features/schedules # 69 passed
flutter test # 686 before merging main;
# 704 on the merged tree
flutter build web # ✓ Built build/web
flutter build web -t tool/schedule_editor_probe_app.dart \
-o build/schedule_editor_probe_web # ✓ Built
node --check tool/schedule_editor_probe.mjs # clean
OPENCODE_ARTIFACT_DIR=…/78/public/s1-form-captures \
node tool/schedule_editor_probe.mjs # all checks passed
```
After merging the current `main` into `flutter/schedule-form` (conflict-free;
the incoming work was unrelated template and chat-composer state changes), the
same checks were re-run on the merged tree: `flutter analyze` clean, 69 schedules
tests, 704 whole-app tests, `flutter build web`, and all six fixture probe checks
with no page errors.
Browser checks that actually ran in real headless Chrome against the fixture:
- blank submit: 0 callbacks, both field errors exposed;
- first valid submit: pending state, 1 callback, a second click left the count at
1;
- refusal: `lastError = conflict: revision 13 is stale`, `records = 0`, name and
prompt still `Probe schedule` / `Summarise the release notes.`, and the visible
line contains `Your draft is preserved.`;
- retry: exactly one accepted record, deep-equal to
`{id:0, name:"Probe schedule", pipeline_id:4, version:2, enabled:true,
input:{prompt:"Summarise the release notes."}, workspace:"/srv/research",
rule:{every:"24h", timezone:"Europe/London"}, notify_mode:"auto"}`;
- 320px at 2x text: labels/helpers and both actions still present and readable;
- Cupertino dark at 390px: native fields, switch, checkboxes and actions rendered.
Captures (shared artifact):
```
/Users/alan/.local/share/pipelines/data/artifacts/78/public/s1-form-captures/
s1-form-material-390-invalid.png
s1-form-material-390-refusal.png
s1-form-material-390-record.png
s1-form-material-320-2x-top.png
s1-form-material-320-2x-bottom.png
s1-form-cupertino-dark-390-top.png
s1-form-cupertino-dark-390-bottom.png
manifest.json
```
The refusal copy is visible in
`s1-form-material-390-refusal.png`; the exact accepted record is visible in
`s1-form-material-390-record.png`; wrapping at 320/2x is visible in the two
`320-2x` captures.
## Full diff
Every path is new; no existing file is modified. The reviewed patch is committed
as `feat(app): add native saved-schedule editor form` on
`flutter/schedule-form`, followed by a conflict-free merge of `main`. The
reviewed patch snapshot, taken before these landing-state note edits, is saved
at:
`/Users/alan/.local/share/pipelines/data/artifacts/78/public/s1-form.diff`
## Honest limits
- **Committed but not deployed.** The candidate commit is merged with `main` and
checked on `flutter/schedule-form`; no push, deployment or canonical URL
change was performed by this work.
- **Not wired into the normal Schedules screen or shell.** There is no editor
dialog/route, no `screen.dart` integration and no navigation; the Schedules
destination's editor entry is a later integration slice.
- **No save engine, repository, network, create/update/pause/delete.** The form
only calls its injected callback and never opens a socket. The existing draft
and repository were not changed.
- **Advanced run options stay preserved but are not editable** in this slice
(`model`, stage models, other input keys, write paths, allow tools, title,
output format). No control was invented for them.
- **Timezone validity remains the landed draft's structural check.** The UI only
displays the draft's error; Dart still has no IANA database here.
- **Mobile unverified.** Only web-targeted Flutter tests/analyze/build ran. No
Android/iOS build, emulator, ADB or device was used.
- **Live server unverified.** Browser evidence is fixture-only; no production
authentication, schedule or run was created or changed.
- **Refusal prefix is the caller's error text.** The real `ProtocolError` has a
clean `toString()`; the fixture throws a custom refusal so the capture does not
show Dart's `Bad state:` prefix from `StateError`.