145 lines
8.3 KiB
Markdown
145 lines
8.3 KiB
Markdown
# 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.
|