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

8.3 KiB
Raw Blame History

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 ExcludeSemanticsd 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.