feat(app): graph pan, zoom and expanded view
This commit is contained in:
@@ -0,0 +1,144 @@
|
||||
# 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.
|
||||
Reference in New Issue
Block a user