Files
pipelines/app/notes/G2-zoom.md
T

145 lines
8.3 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.
# Graph viewport: pan, zoom, fit and expanded
The measured definition/run canvases now share one viewport layer. Nothing in
the graph's wiring changed: `DefinitionGraphView` and `RunGraphView` keep their
existing props and call sites, and the pipeline Graph tab / run detail open the
expanded presentation without edits to those tabs.
## Landed
- `lib/features/graph/viewport/graph_viewport_math.dart` — the web graph's
`fitScale`/`clampOffset` rules (padding 24, min 0.3, max 3, at least 40px of
the scaled graph visible) plus the `offset + point * scale` matrix.
- `lib/features/graph/viewport/graph_viewport_controller.dart` — owns the
`TransformationController`, auto-fits on first layout, re-fits a resize only
before the reader interacts, clamps every later transform, and round-trips a
`GraphViewportSnapshot`.
- `lib/features/graph/viewport/graph_viewport.dart` — the bounded canvas: the
host's `InteractiveViewer` gestures (drag, pinch, wheel, trackpad) with an
infinite boundary margin so the graph's own fit/bounds win, plus native Fit
and Expand controls (`Fit graph to view`, `Expand graph`).
- `lib/features/graph/viewport/graph_expanded_view.dart` — a native full-screen
presentation (`Scaffold`/`CupertinoPageScaffold`) with one visible `Close`
action, `openGraphExpanded()` as the widget/callback seam, and an optional
fixed `header` above the canvas. It fits the larger box exactly as the web
re-fits when its panel expands, keeps the selected node selected, re-fits a
resize until the reader interacts and clamps one afterwards. It owns a
separate controller, so closing restores the inline transform exactly.
- `DefinitionGraphView`/`RunGraphView` now wrap their measured content in
`GraphViewport`; `RunGraphCanvas` is the passive content only (the viewer
moved out of it). `DefinitionGraphCanvas` owns the measured definition
composition, and `RunGraphHeader` owns the route legend + elapsed line and is
carried into the expanded run presentation. Node sizes, routing,
executed/unvisited evidence, labels and legend are unchanged.
## Behavior and bounds
- The graph is fitted on first layout with 24px padding and never upscaled past
1:1, before the first paint: the first layout attaches synchronously, when
nothing is listening to the transform yet, rather than flashing an identity
transform for a frame.
- Scale is clamped to 0.3–3 and a drag can never leave an empty viewport
(40px minimum visible per axis).
- Pinch/wheel zoom anchors the graph point under the moving focal point; a tap
that does not move still reaches the native node under the pointer because
hit-testing follows the same transform.
- Fit and Expand are stock host buttons with one accessible name and the
button's own tap action on both hosts. The icon is the only excluded child
and `MergeSemantics` folds the real button action into the labelled node; a
hand-written sibling `Semantics` around an `ExcludeSemantics`d button would
announce the control with no action at all.
- Single taps select nodes; dragging over a node pans instead of selecting.
- The canvas consumes gestures only inside its own box. An ancestor scroll view
keeps scrolling for gestures outside the canvas, and the canvas never pans
from a drag that starts outside it.
- Expanded draws the same canvas at its own fit, keeps the legend (run graph),
keeps the selection, and leaves the inline canvas untouched.
## Checks (final tree)
From `app/` with Flutter 3.44.6 / Dart 3.12.2:
- `flutter analyze` — **No issues found**.
- `flutter test` — **1025 tests pass** (1m 06s in this run).
- `flutter test test/features/graph` — **175 pass**.
- `flutter test test/features/graph/viewport` — **20 tests pass**
(8 math/controller, 9 viewport widget, 3 expanded), covering:
- drag pans and pan stays bounded;
- pinch clamps at 0.3 and 3;
- zoom keeps the graph point under the moving focal point;
- the first painted frame is already fitted;
- Fit restores the fitted scale/offset;
- tap selects the node visually under the pointer after a transform (synthetic
targets and real `DefinitionGraphView` nodes);
- ancestor scroll is not hijacked outside the canvas;
- Fit and Expand are labelled buttons with a tap action on Material and
Cupertino, and performing that action runs the real callback;
- 320px/2x on Material and dark Cupertino;
- expanded fits the larger canvas, preserves selection and returns the inline
state exactly;
- a rotation re-clamps the expanded transform into the new box.
- `flutter build web` — succeeds for the app and the probe target.
- Real Chrome probe (`tool/graph_zoom_probe.dart` + `tool/graph_zoom_probe.mjs`,
loopback server, OS-assigned port) re-run against this final source, 7 runs:
- pipeline graph: Material light 1280x800 1x, Material light 320x700 2x,
Cupertino dark 390x844 1x, Cupertino dark 320x700 2x;
- run graph: Material light 1280x800 1x, Material dark 320x700 2x,
Cupertino dark 390x844 1x.
Each asserted a real drag moved a node, wheel zoom grew it, Fit restored it,
Expand opened the titled full-screen canvas with the selected node still
announced selected, and Close returned to the same inline place and selection.
42 captures (initial/panned/zoomed/fitted/expanded/restored per run) were
regenerated after the last source edit and are in
`/Users/alan/.local/share/pipelines/data/artifacts/101/public/graph-zoom-captures/`.
- `dart format --output=none --set-exit-if-changed` on the changed Dart files —
0 changed; `git diff --check` — clean.
## Corrections from actual checks
- The transform's z axis must be scaled with x/y: `getMaxScaleOnAxis` otherwise
reported 1.0 for a 0.8 fit and InteractiveViewer's own pinch math used the
wrong scale. Fixed in `graphViewportMatrix`.
- Two existing measurement tests compared on-screen rectangles, which now
include the fit scale. They divide by the current scale and assert the
measured graph-space extent instead; the assertions about wrapping and
overlap are unchanged.
- Cupertino's full-screen route added its own `Cancel` leading button next to
the explicit Close; `automaticallyImplyLeading: false` leaves the one Close
action.
- `tester.drag` can lose the pre-acceptance movement to the pan slop; gesture
tests warm up past the slop and measure from the accepted transform, and the
browser probe pans with eight real pointer moves.
- The first implementation excluded the whole Cupertino button from semantics
and put the label on a sibling node: VoiceOver/TalkBack saw a labelled button
with no tap action. The exclusion now covers only the icon and
`MergeSemantics` merges the host button's action; the regression test performs
the semantics action itself, not a pointer tap.
- Material controls previously had only a tooltip as their accessible name. Both
hosts now expose one explicit label (`Fit graph to view` / `Expand graph`);
Material keeps the tooltip for pointer hover, excluded from semantics so the
name is not duplicated.
- The inline canvas used to paint one identity-transform frame before the
post-frame fit. The first layout now attaches before its child viewer exists,
and the regression test pumps exactly once.
- Expanded used to keep the small inline scale, unlike the web, which calls
`fit()` after growing the panel. It now fits its own canvas and re-clamps (or
re-fits) on resize; the inline place/selection still return unchanged on
Close.
- The expanded run canvas had no route legend; `RunGraphHeader` now travels
with it.
## Limits
- Inside an ancestor scroll view, a **vertical** drag that starts on the canvas
is claimed by the scrollable (Flutter's gesture arena gives the 18px vertical
drag the win over the 36px pan slop); horizontal drags and pinch stay with the
canvas. The graph is not inside a scrollable in either current tab. Outside
the canvas the list scrolls normally, which is the accepted behavior here.
- Opening expanded fits the graph rather than keeping the inline place (web
behavior); closing still restores the inline transform exactly.
- Web only: Android/iOS builds, device gestures and OS behavior are unverified.
- `run_graph_view.dart` remains over the 250-line aim (324 lines: measurement,
evidence and viewport composition; the legend/header and definition canvas
were split out). The new viewport files and viewport test files are all under
250 lines.