Files
pipelines/app/notes/T1-gallery.md
T

184 lines
11 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# T1 — reusable native Templates gallery
Manager acceptance: re-ran the templates suite (38 tests) and rebuilt the
in-process fixture. Seven probe checks pass with seven captures under approved
temp/templates-gallery-browser; the selected-template capture was inspected and
shows metadata, the verbatim selectable source and the native create action with
one bar. No real template was created or submitted; every request came from the
fixture gateway. Settings/route registration and a post-create pipelines-list
refresh are still manager wiring, not claimed here.
## Result
`TemplatesScreen` is one reusable gallery over the server's actual template
catalogue. It lists every `list_templates` row, opens the selected template's
metadata and its source byte-for-byte in the host's selectable body, and offers
the browser's one create action. That action calls the already-landed
`showTemplateCreateDialog` unchanged, so validate-then-submit, Cancel,
create-only `submit` and the single accepted `detail` stay in the existing
prompt. The accepted detail is forwarded through the optional `onCreated`
callback.
A refused refresh is reported above whichever body is current, including an open
template, with the host's native Retry; the selection and already-read rows are
kept. The screen's loading state, late-reply guard and single create path are
unchanged.
Nothing is registered in the shell, Settings, routes or application; the
manager owns that next. No pipeline/gallery/create code was rewritten and no
run, schedule, publish, cancel or graph control exists here.
## Files (all new; no tracked file modified)
| File | Lines | Responsibility |
| --- | ---: | --- |
| `lib/features/templates/screen.dart` | 208 | Load/selection/create state, late-reply sequencing, failure banner above either body, embedded flag, system back |
| `lib/features/templates/ui/template_gallery.dart` | 138 | Catalog rows and honest loading/empty/full-failure states |
| `lib/features/templates/ui/template_detail.dart` | 168 | Browser wording, metadata, verbatim selectable source, create action, embedded Back row |
| `lib/features/templates/ui/templates_failure.dart` | 118 | Full failure state and the screen-level failed-refresh banner, each with native Retry |
| `lib/features/templates/ui/templates_frame.dart` | 104 | Native standalone app bar or embedded Refresh row; Back/Refresh controls |
| `test/features/templates/ui/template_gallery_test_support.dart` | 112 | Recording gateway, catalogue fixtures, Material/Cupertino host pump |
| `test/features/templates/ui/template_gallery_screen_test.dart` | 379 | States, retry, refresh, detail-refresh failure (both hosts, embedded), back, embedded, 2x, late/disposed replies |
| `test/features/templates/ui/template_gallery_create_test.dart` | 104 | Cancel sends nothing, verify+submit once, optional callback, Cupertino prompt |
| `tool/templates_gallery_probe.dart` | 178 | Isolated in-process fixture entry; default, empty and detail-refresh-refusal scenarios |
| `tool/templates_gallery_probe.mjs` | 386 | Loopback static server + real headless Chrome driver |
| `notes/T1-gallery.md` | — | This evidence |
`TemplateEntry`, `TemplateRepository`, `TemplateRepositoryException`,
`ApiGateway`, `showTemplateCreateDialog` and its wording/keys are reused
unchanged. `pubspec.*`, `lib/main.dart`, `lib/application/`, `lib/shell/`,
Settings, routes, Pipelines, `web/`, the Go server and `android/` were not
touched.
## Behaviour
- Gallery wording is the browser's: `Loading templates…`, `No templates are
available on this server.`, a blank catalogue name as `(unnamed template)`,
description verbatim, and a blank detail heading falling back to the key.
- Detail shows the description (when non-blank), `Key`, `Includes a schedule`
(when true), `Definition source`, and the server's complete source in
`SelectableText`. The source is never trimmed, re-indented or re-encoded.
- The action is exactly `Create pipeline from this template`. It calls
`showTemplateCreateDialog` with the current repository, the selected entry and
the host's native flag. Opening the prompt, typing, or Cancel sends nothing.
Only the dialog's Create validates and then submits create-only; an accepted
detail reaches `onCreated` exactly once.
- Standalone Material uses `Scaffold`/`AppBar` with a native `BackButton` when a
template is open and a tooltip `Refresh` action; Cupertino uses
`CupertinoPageScaffold`/`CupertinoNavigationBar` with the native back chevron
and refresh icon. Doors are opened on the detail as this screen's own page, so
Android system back also returns to the gallery via `PopScope`.
- `embedded: true` drops the app bar, keeps a Refresh control at the body's
trailing top edge and shows a native Back row inside the detail, matching the
shell-owned-navigation contract used by other feature screens.
- Loading, empty and refusal have their own truthful states. A refusal shows the
server's own text and `Retry`; a refresh failure keeps already-loaded rows and
shows the refusal/`Retry` above them instead of blanking the gallery. The same
banner is rendered above an open template, so pressing Refresh on the detail
never fails silently; Retry re-reads with the template and rows kept.
- Only the newest `list_templates` generation may publish. A gateway change
clears the old server's rows and selection, an older reply is ignored, and a
reply completing after disposal is dropped (no `setState`).
- No stage-count read, stage list, Graph tab or mini graph is included: this
slice deliberately sends no per-card `validate`. The browser's stage count is
therefore not claimed here. The detail's metadata is description, key and
schedule flag; its source is complete.
## Checks actually run
```
cd app
flutter analyze # No issues found
dart format --output=none --set-exit-if-changed \
lib/features/templates test/features/templates/ui/template_gallery_*.dart \
tool/templates_gallery_probe.dart # 0 changed
flutter test test/features/templates # 37 passed
flutter test # 690 passed
flutter build web -o <private>/web-normal # ✓ Built
flutter build web --target=tool/templates_gallery_probe.dart \
-o <private>/probe-web # ✓ Built
```
The focused suite covers: loading then catalogue; empty; refusal + Retry;
failed refresh retaining rows; a failed refresh with the detail open on Material
and Cupertino, including the native Retry control and the template staying
open; the same failure in embedded mode; refresh re-reading without losing
selection; selection showing metadata/source with no validate/submit;
native/system back; embedded framing; Cupertino list/back/detail controls; 2x at
360×640 with no overflow; stale reply ignored after a gateway replacement; late
reply after disposal; Cancel sending nothing; exact `validate`/`submit` payloads;
callback once; optional callback; Cupertino prompt.
## Browser evidence (real headless Chrome, loopback only)
The probe's gateway is in-process; it never opens a socket and never contacts a
real Pipelines server. All runs are dark (`MaterialApp` standard dark theme /
`CupertinoThemeData(brightness: dark)`), with no font, colour or component-size
overrides. Each default run asserts: refusal + Retry; loading; actual rows;
selection metadata + `Definition source`; back; refresh adding
`Added after refresh`; Cancel with zero requests; accepted create with exactly
one validate and submit, exact
`{name: "Probe release", source: <verbatim fixture>, create_only: true}`,
callback once, and Close sending nothing.
- Material dark, 390×844, 1x — `public/t1-gallery/`
(`error`, `loading`, `gallery`, `detail`, `refreshed`, `create-blank`, `created`).
- Material dark, 360×640, 2x text — `public/t1-gallery-2x/` (same seven states).
- Cupertino dark, 390×844, 1x — `public/t1-gallery-cupertino-1x/` (same seven).
- Cupertino dark, 360×640, 2x text — `public/t1-gallery-cupertino/` (same seven).
- Material dark empty catalogue — `public/t1-gallery-empty/t1-gallery-empty-empty.png`.
- Material dark failed refresh with the detail open —
`public/t1-gallery-detail-refresh/` (`detail-refresh-error`,
`detail-refresh-retried`).
- Cupertino dark failed refresh with the detail open —
`public/t1-gallery-detail-refresh-cupertino/` (same two states).
The new scenario loads the catalogue, opens `Release workflow`, presses Refresh
and the fixture read genuinely refuses. The run asserts the refusal and Retry
are present above the still-open definition source, that exactly two
`list_templates` reads and no `validate`/`submit` happened, then presses Retry,
asserts the banner clears, the template stays open and a third read happened.
Inspected both Material and Cupertino captures: the native banner sits above the
detail, then disappears after Retry without losing the template.
Inspected screenshots: the Material dark gallery/detail, the 2x detail with
wrapped action and title, the Cupertino 1x gallery/detail, the 2x Cupertino
gallery (names now wrap to two lines rather than ellipsizing), the error/Retry
state and the created dialog with the exact success line.
## Task diff
```
?? app/lib/features/templates/screen.dart
?? app/lib/features/templates/ui/template_detail.dart
?? app/lib/features/templates/ui/template_gallery.dart
?? app/lib/features/templates/ui/templates_failure.dart
?? app/lib/features/templates/ui/templates_frame.dart
?? app/test/features/templates/ui/template_gallery_create_test.dart
?? app/test/features/templates/ui/template_gallery_screen_test.dart
?? app/test/features/templates/ui/template_gallery_test_support.dart
?? app/tool/templates_gallery_probe.dart
?? app/tool/templates_gallery_probe.mjs
?? app/notes/T1-gallery.md
```
All are additions in the working tree. No tracked file changed, no concurrent
lane or manager commit was modified, and nothing was staged, committed, pushed
or deployed. `git diff --check` is clean.
## Honest limits
- Not wired into the shell/Settings/routes; this is reusable source, not a
normal-app preview entry. The manager owns registration.
- No real Pipelines server, credentials, operator pipeline or create request was
touched. Browser evidence uses the in-process fake gateway.
- Mobile (Android/iOS) is unverified: no Android/iOS build, emulator, device or
ADB. The Cupertino captures are Chrome's rendering of Cupertino widgets, not
iOS; VoiceOver/TalkBack was not run.
- Stage counts, stage lists and the Graph tab are intentionally not implemented
in this slice (no per-card validate), so they are not claimed as parity here.
- Browser captures remain standalone use only; `embedded: true` is covered by
widget tests, not by the headless-Chrome probe.
- `/artifacts`/live authenticated data and the real dark app-shell theme were
not exercised; the probe supplies the standard dark host themes.