Implement per-axis pan and zoom configuration

[Alek99]

Summary

• implement the full flat pan/zoom configuration contract across Python, the wire payload, the browser client, notebooks, and Reflex
• add default_drag_action, exact-ID pan_axes/zoom_axes/reset_axes, per-axis zoom_limits, and wheel/box/button/double-click source switches
• replace the scalar browser viewport with canonical per-axis ranges, including independent secondary axes such as y2
• apply one clamped mutation path to pan, wheel zoom, box zoom, toolbar zoom, reset, linked ranges, and programmatic updates
• emit semantic view events with ranges, source, axes, phase, and interaction_id; remove the public view_change behavior flag and gate Python transport on callback presence
• preserve selection when resetting the view and prevent zoom-out beyond the original window by default with (1.0, None)
• contain pan-locked axes: an axis zoom_axes can navigate but pan_axes cannot never leaves its home window (cursor-anchored zoom embeds a translation, so exclusion without containment would still let zoom pan the axis); zoomed in, drag still slides it inside home
• add the complete design document plus x-only histogram, default box-zoom histogram, dual-axis, and expanded bar-chart examples
• rebuild the shipped widget, standalone clients, and generated Reflex gallery assets

Why

The previous viewport model assumed one x and one y range. That made source-specific behavior inconsistent and could not represent charts where y must remain fixed while y2 pans or zooms independently. Zoom enablement also did not express limits such as “never zoom out past the original window,” and event transport depended on a redundant public flag.

This change makes capabilities, drag choice, exact axis policy, input source, range limits, reset, linking, and event transport independent while keeping omitted configuration backwards compatible.

Developer impact

A normal x/y chart still pans and zooms both axes. Every zoom-enabled axis now defaults to a minimum magnification of 1.0, so users cannot zoom out past its home span. Applications can opt out with zoom_limits=(None, None) or configure limits by exact axis ID.

Multi-axis charts can use policies such as:

xy.interaction_config(
    default_drag_action="zoom",
    pan_axes=("x", "y2"),
    zoom_axes=("x", "y2"),
    zoom_limits={"x": (1.0, None), "y2": (0.5, 32.0)},
    reset_axes=("x", "y2"),
)

Excluding an axis from pan_axes while zoom can still navigate it contains the axis: its window can never extend past its home extents on any mutation path, and a zoomed-in view can still be dragged within them (the drag pins flush at the home edge). At home magnification a contained axis cannot move at all. bounds= remains the explicit hard envelope for positions beyond home, and navigation=False charts follow linked or programmatic updates freely.

Touch pinch and a dedicated keyboard viewport-navigation mode remain explicitly deferred; existing keyboard point exploration is preserved.

Validation

• .venv/bin/pytest -q — 2,078 passed, 5 skipped, including headless-Chromium probes locking the wheel-gesture terminal end event and the pan-lock containment invariant (both verified fail-first against the pre-change client)
• .venv/bin/ruff check and ruff format --check over the repo
• .venv/bin/python scripts/render_smoke_nonumpy.py
• .venv/bin/python scripts/reflex_lifecycle_smoke.py — 23 charts × loads/remounts/reloads/reveals
• node js/build.mjs
• reflex compile --dry in examples/reflex
• production example app verified in-browser:
  • x and y2 zoom independently while reversed primary y remains fixed
  • zoom-out clamps at the 100% home window
  • histogram mounts with default_drag_action="zoom"

[codspeed-hq]

Merging this PR will not alter performance

✅ 94 untouched benchmarks
⏩ 1 skipped benchmark¹

---

_{Comparing agent/add-axis-scoped-zoom-examples (dccf7c8) with main (09eb9f0)}

Footnotes

1. 1 benchmark was skipped, so the baseline result was used instead. If it was deleted from the codebase, click here and archive it to remove it from the performance reports. ↩

[greptile-apps]

Greptile Summary

This PR adds per-axis pan and zoom configuration across the chart stack. The main changes are:

• Per-axis pan, zoom, reset, and zoom-limit policies.
• Canonical per-axis ranges and semantic view events.
• Unified clamping for gesture, toolbar, linked, and programmatic updates.
• Updated Python, notebook, Reflex, browser, documentation, examples, and generated assets.
• Deterministic coverage for the wheel-gesture terminal event race.

Confidence Score: 5/5

This looks safe to merge.

The wheel timer is cancelled before the queued frame can race the old deadline. The browser test checks for one final event carrying the committed ranges.

No blocking issue was found in the updated path.

T-Rex Logs

What T-Rex did

• Validated that the test run completed with exit code 0 and that the exact pytest command and working directory are captured in the after-state log.
• Validated the probe-values log shows all listed booleans true for chainYContained, chainXEscaped, programmaticYContained, dragMovedLockedAxis, dragClampedAtHomeEdge, freeXEscaped, and freeYStayedHome.
• Compared the before and after visual artifacts and confirmed the chart's render region changed after wheel zoom and drag interaction.
• Verified that the artifact set includes the videos, poster frames, and logs that document the test run, probe results, and UI-state changes for reviewer inspection.

_{Ran code and verified through T-Rex}

Important Files Changed

Filename	Overview
js/src/53_interaction.js	Adds per-axis navigation policies and cancels the wheel end timer when a new delta is queued.
tests/test_wheel_gesture_end.py	Adds deterministic browser coverage for wheel deltas arriving immediately before the gesture deadline.

_{Reviews (7): Last reviewed commit: "Merge main: vectorized style channels (#..." | Re-trigger Greptile}

[masenf]

the example/reflex app needs to be rewritten, it's unmaintainable in its current state. i think we can just get rid of the static html generation and just define the reflex charts as regular python functions from build_charts.py (and use getsource() so the displayed code and chart doesn't differ).

as it is now, the main changes to the examples are in the source string, rather than the code that builds the html 🥲

i'll do that in a second PR based on this branch: #124

[masenf]

one thing i still think is a little weird is you can set an axis to zoom but not pan. then once the chart is zoomed, you cannot pan the zoomed view, but you can achieve the same effect by zooming out, then zooming in on a different part of the graph. idk how exactly to solve it yet, but it feels weird.

[Alek99]

@greptile

[Alek99]

@masenf on both review comments:

Examples rewrite — agreed, and #124 looks like the right shape. I've kept this branch additive-only (no force pushes) since you branched it.

Zoom-without-pan — your instinct was right, and it's worse than the two-step route: cursor-anchored zoom is a scaling composed with a translation (Δcenter = span · (anchor − ½) · (1 − f)), so a zoom-in at one cursor position followed by a zoom-out at another is an exact pan of the "locked" axis — spans cancel bit-for-bit, only the translation survives. Box zoom could translate it in a single drag. The default zoom_limits=(1.0, None) caps span, not position, so it never stopped any of this.

560f51f resolves it by making exclusion from pan_axes mean containment rather than gesture removal:

• a pan-locked axis's window can never extend past its home extents, on any mutation path (wheel/box/button zoom, drag, linked, programmatic — it's one clamp in the shared pipeline);
• zoomed in, plain drag now works on the locked axis — it slides within home and pins flush at the edge — so the "zoom out then zoom in somewhere else" workaround you described becomes a plain drag;
• at home magnification the window fills the envelope and can't move at all, which is the behavior you already liked;
• navigation=False charts aren't contained, so read-only followers still track a controller freely, and bounds= remains the explicit envelope when you want positions past home.

Spec: interaction.md §2.2 states the invariant; the design doc threads it through the pipeline/precedence/zoom-limit/linked sections. tests/test_pan_lock_containment.py drives the real client in headless Chromium and was verified fail-first (the wheel-chain escape walks the locked axis out of home on the pre-change client).

One adjacent pre-existing quirk worth a follow-up: the wheel anchor divides by the canvas rect while pan uses the plot rect, so the zoom focal point drifts from the cursor by the axis-margin fraction. Identical on the base commit, so I left it out of this PR.