@jbrowse/core 4.2.1 → 5.0.0-beta.1

package/esm/util/wheelZoom.js

@@ -0,0 +1,231 @@
+// Shared wheel-zoom math and event handling for linear genome views. The LGV
+// wheel handler, the breakpoint-split overlay and the synteny canvas all zoom on
+// ctrl/scroll-zoom wheel gestures and must behave identically, so the normalizer,
+// the rate limit and the whole gesture decision matrix live here —
+// createWheelZoomController below is what each of those three actually runs.
+import { transaction } from 'mobx';
+import { createFrameCoalescer } from './frameCoalescer.js';
+import { trackPointerPresence } from './pointerPresence.js';
+// max zoom delta per millisecond — equivalent to 0.2 per frame at 60fps
+export const MAX_ZOOM_RATE_PER_MS = 0.2 / 16.67;
+// Scroll-zoom (plain wheel with the scrollZoom preference on) divides by a fixed
+// amount for a smooth proportional feel, rather than the adaptive
+// getZoomNormalizer used for ctrl/pinch zoom where device deltas vary wildly.
+export const SCROLL_ZOOM_FACTOR_DIVISOR = 500;
+// The per-event contribution to the zoom accumulator, given a wheel delta
+// already normalized to pixels via normalizeWheelDelta. ctrl/pinch zoom uses the
+// adaptive normalizer; scroll-zoom uses the fixed divisor. Single source of the
+// zoom-step feel so every wheel handler (LGV, breakpoint overlay, synteny)
+// zooms identically for the same gesture.
+export function wheelZoomAccum(normalizedDeltaY, isCtrlZoom) {
+    return (normalizedDeltaY /
+        (isCtrlZoom
+            ? getZoomNormalizer(normalizedDeltaY)
+            : SCROLL_ZOOM_FACTOR_DIVISOR));
+}
+// larger wheel deltas (e.g. mouse wheel notches) divide by more so a single
+// notch produces a consistent zoom step regardless of device delta magnitude
+export function getZoomNormalizer(deltaY) {
+    const abs = Math.abs(deltaY);
+    if (abs < 6) {
+        return 25;
+    }
+    if (abs > 150) {
+        return 500;
+    }
+    if (abs > 30) {
+        return 150;
+    }
+    return 75;
+}
+// One wheel notch in line mode (deltaMode 1) is roughly this many pixels, and a
+// page (deltaMode 2) roughly WHEEL_PAGE_HEIGHT — the values Facebook's
+// normalize-wheel uses, the de-facto cross-browser convention. Pixel mode (0),
+// which trackpads and modern mice report, passes through untouched.
+const WHEEL_LINE_HEIGHT = 40;
+const WHEEL_PAGE_HEIGHT = 800;
+// Convert a WheelEvent delta from its deltaMode units to pixels. Panel-scroll
+// callers pass the viewport height as `pageHeight` so a page maps to exactly one
+// screen; the zoom path omits it and takes the default. Single normalizer for
+// both the zoom math here and the vertical-scroll handlers so a notch means the
+// same thing everywhere.
+export function normalizeWheelDelta(delta, deltaMode, pageHeight = WHEEL_PAGE_HEIGHT) {
+    return deltaMode === 1
+        ? delta * WHEEL_LINE_HEIGHT
+        : deltaMode === 2
+            ? delta * pageHeight
+            : delta;
+}
+// elapsed since the previous animation frame, clamped to 100ms and defaulting
+// to one 60fps frame when there is no prior frame (first event or post-resume)
+export function wheelFrameElapsedMs(now, lastRafTime) {
+    return Math.min(100, lastRafTime !== null ? now - lastRafTime : 16.67);
+}
+// Accumulate horizontal scroll across a frame, restarting from zero when the
+// gesture reverses direction so a flick the opposite way isn't cancelled out by
+// leftover momentum.
+export function accumulateScroll(prev, deltaX) {
+    const reversed = prev !== 0 && Math.sign(deltaX) !== Math.sign(prev);
+    return (reversed ? 0 : prev) + deltaX;
+}
+// A pinch/scroll-zoom gesture fires a continuous stream of wheel events, so we
+// treat the view as "actively zooming" until this many ms pass with no zoom
+// event. While actively zooming, callers ignore horizontal deltas: trackpads
+// emit an unintentional side-scroll mid-gesture that would otherwise pan the
+// view out from under the user.
+export const ZOOM_ACTIVE_WINDOW_MS = 100;
+// `now` and `lastZoomTime` are both wheel-event timeStamps (same clock).
+// lastZoomTime is null before any zoom has occurred.
+export function isActivelyZooming(now, lastZoomTime) {
+    return lastZoomTime !== null && now - lastZoomTime < ZOOM_ACTIVE_WINDOW_MS;
+}
+// apply an accumulated zoom amount to bpPerPx, rate-limited so a burst of wheel
+// events can't zoom faster than MAX_ZOOM_RATE_PER_MS over the frame's elapsed
+export function applyZoomAccum(bpPerPx, zoomAccum, elapsedMs) {
+    const max = MAX_ZOOM_RATE_PER_MS * elapsedMs;
+    const d = Math.max(-max, Math.min(max, zoomAccum));
+    return d > 0 ? bpPerPx * (1 + d) : bpPerPx / (1 - d);
+}
+/**
+ * The one wheel gesture handler for linear views. Its decision matrix:
+ *
+ *   - ctrl/meta+wheel, or (scrollZoom && |dy| >= |dx|)  → zoom about the cursor
+ *   - shift+wheel while scrollZoom is on                → declined, we pass
+ *   - a horizontal delta, unless one arrives mid-zoom   → pan by dx
+ *
+ * Declining shift is what leaves a nested panel its own scroll
+ * (`usePanelVirtualScroll`) — it is not a way back to the page. Browsers turn
+ * shift+wheel into *horizontal* scrolling, so what a view declines here scrolls
+ * the page sideways or not at all. The vertical way out is spatial rather than
+ * modal: JBrowse binds this below the view's sticky header, leaving that header
+ * as a gutter the wheel still scrolls (LinearGenomeViewContainer's tracksRef).
+ *
+ * The listener is non-passive so it can preventDefault to suppress native scroll
+ * during a zoom. To pay for that it only accumulates deltas: every model write
+ * happens in one requestAnimationFrame, so a burst of events (fast trackpad,
+ * inertial scroll) collapses to a single update per frame instead of thrashing
+ * the views once per event.
+ *
+ * Returns its disposer.
+ */
+export function createWheelZoomController({ element, resolveTarget, swallowUnhandled = false, releaseOnPointerLeave = false, onEvent, }) {
+    const frame = createFrameCoalescer();
+    const s = {
+        scrollDelta: 0,
+        zoomAccum: 0,
+        target: undefined,
+        lastClientX: 0,
+        originLeft: undefined,
+        lastRafTime: null,
+        lastZoomTime: null,
+        lastEventTime: null,
+        warnedNonCancelable: false,
+    };
+    // see releaseOnPointerLeave: drop any in-flight accumulation and stop consuming
+    // latched wheel events, so a continued gesture pans/zooms nothing and chains to
+    // the page instead of staying stuck to this element
+    const presence = releaseOnPointerLeave
+        ? trackPointerPresence(element, () => {
+            s.scrollDelta = 0;
+            s.zoomAccum = 0;
+            s.originLeft = undefined;
+        })
+        : undefined;
+    function flush(now) {
+        const elapsed = wheelFrameElapsedMs(now, s.lastRafTime);
+        s.lastRafTime = now;
+        const { target } = s;
+        if (target) {
+            const origin = target.originElement();
+            if (s.zoomAccum !== 0 && origin && s.originLeft === undefined) {
+                s.originLeft = origin.getBoundingClientRect().left;
+            }
+            const originLeft = s.originLeft;
+            transaction(() => {
+                if (s.zoomAccum !== 0 && originLeft !== undefined) {
+                    const offset = s.lastClientX - originLeft;
+                    for (const view of target.views) {
+                        view.zoomTo(applyZoomAccum(view.bpPerPx, s.zoomAccum, elapsed), offset);
+                    }
+                }
+                if (s.scrollDelta !== 0) {
+                    for (const view of target.views) {
+                        view.horizontalScroll(s.scrollDelta);
+                    }
+                }
+            });
+        }
+        s.zoomAccum = 0;
+        s.scrollDelta = 0;
+    }
+    function onWheel(event) {
+        onEvent?.(event);
+        const gated = presence !== undefined && !presence.isOver;
+        const target = gated ? undefined : resolveTarget(event);
+        if (target && !(event.shiftKey && target.scrollZoom)) {
+            // a gap longer than the frame-elapsed clamp means this event starts a new
+            // gesture, so the previous frame time is meaningless — including when it
+            // predates a spell in a backgrounded tab, where a huge elapsed would
+            // otherwise lift the zoom rate limit on the first frame back
+            if (!isActivelyZooming(event.timeStamp, s.lastEventTime)) {
+                s.lastRafTime = null;
+                s.originLeft = undefined;
+            }
+            s.lastEventTime = event.timeStamp;
+            s.target = target;
+            const deltaY = normalizeWheelDelta(event.deltaY, event.deltaMode);
+            const deltaX = normalizeWheelDelta(event.deltaX, event.deltaMode);
+            const isCtrlZoom = event.ctrlKey || event.metaKey;
+            const isZoom = isCtrlZoom ||
+                (target.scrollZoom && Math.abs(deltaY) >= Math.abs(deltaX));
+            if (isZoom) {
+                // warn once per latched run, not once per event — a non-cancelable
+                // sequence fires ~100 events/sec and console.warn is not free
+                if (event.cancelable) {
+                    s.warnedNonCancelable = false;
+                }
+                else if (!s.warnedNonCancelable) {
+                    s.warnedNonCancelable = true;
+                    console.warn('[wheelZoom] wheel event not cancelable — scroll sequence already in progress');
+                }
+                event.preventDefault();
+                s.zoomAccum += wheelZoomAccum(deltaY, isCtrlZoom);
+                s.lastClientX = event.clientX;
+                s.lastZoomTime = event.timeStamp;
+                // drop any side-scroll accumulated earlier this frame — we're zooming,
+                // and a deltaX that arrived just before the zoom is part of the same
+                // noisy gesture
+                s.scrollDelta = 0;
+            }
+            else if (isActivelyZooming(event.timeStamp, s.lastZoomTime)) {
+                // ignore stray horizontal deltas that arrive mid-zoom — trackpads emit
+                // an unintentional side-scroll during a pinch/scroll-zoom gesture that
+                // would otherwise pan the view away from where the user is zooming.
+                // preventDefault anyway so the page itself doesn't scroll instead.
+                event.preventDefault();
+            }
+            else {
+                // With scrollZoom on, swallow the gesture even though it fell outside
+                // the zoom threshold: without this, a diagonal trackpad gesture whose
+                // |deltaX| slightly exceeds |deltaY| slips through and scrolls the page
+                // (shift+wheel above is the deliberate exception). With scrollZoom
+                // off, only swallow what we are about to pan with, so a plain vertical
+                // wheel isn't silently eaten.
+                if (swallowUnhandled ||
+                    target.scrollZoom ||
+                    Math.abs(deltaX) > Math.abs(2 * deltaY)) {
+                    event.preventDefault();
+                }
+                s.scrollDelta = accumulateScroll(s.scrollDelta, deltaX);
+            }
+            frame.schedule(flush);
+        }
+    }
+    element.addEventListener('wheel', onWheel, { passive: false });
+    return () => {
+        element.removeEventListener('wheel', onWheel);
+        presence?.dispose();
+        // so a flush can't fire against a detached view
+        frame.cancel();
+    };
+}

package/esm/util/whenViewSettled.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Wait until a view has either initialized or failed, and report which.
+ *
+ * `initialized` folds in a view's assemblies, so an assembly that fails to load
+ * leaves it false **forever**. A bare `when(() => view.initialized)` therefore
+ * does not fail — it never settles at all, and whatever the caller meant to do
+ * next simply never happens, with no error, no toast and a pending promise left
+ * behind. That has surfaced twice now as two different-looking bugs: an SVG
+ * export hung behind its dialog's spinner, and a launched breakpoint split view
+ * that opened but was never navigated or zoomed.
+ *
+ * Every view exposes a resolved `error` beside `initialized`, so waiting on the
+ * pair turns the hang into something reportable. What to report is the caller's,
+ * because the vocabularies genuinely differ — an export says "cannot export"
+ * and attaches its failures for `awaitSvgRenders` to collect, while a launcher
+ * says the launch failed — which is why this returns the answer instead of
+ * throwing one wording at both.
+ *
+ * No time bound, deliberately: `initialized || error` is a terminal pair, so a
+ * slow-but-healthy remote assembly is waited out rather than guessed at.
+ *
+ * @returns true if the view initialized, false if it settled on an error
+ */
+export declare function whenViewSettled(view: {
+    initialized: boolean;
+    error: unknown;
+}): Promise<boolean>;

package/esm/util/whenViewSettled.js

@@ -0,0 +1,28 @@
+import { when } from 'mobx';
+/**
+ * Wait until a view has either initialized or failed, and report which.
+ *
+ * `initialized` folds in a view's assemblies, so an assembly that fails to load
+ * leaves it false **forever**. A bare `when(() => view.initialized)` therefore
+ * does not fail — it never settles at all, and whatever the caller meant to do
+ * next simply never happens, with no error, no toast and a pending promise left
+ * behind. That has surfaced twice now as two different-looking bugs: an SVG
+ * export hung behind its dialog's spinner, and a launched breakpoint split view
+ * that opened but was never navigated or zoomed.
+ *
+ * Every view exposes a resolved `error` beside `initialized`, so waiting on the
+ * pair turns the hang into something reportable. What to report is the caller's,
+ * because the vocabularies genuinely differ — an export says "cannot export"
+ * and attaches its failures for `awaitSvgRenders` to collect, while a launcher
+ * says the launch failed — which is why this returns the answer instead of
+ * throwing one wording at both.
+ *
+ * No time bound, deliberately: `initialized || error` is a terminal pair, so a
+ * slow-but-healthy remote assembly is waited out rather than guessed at.
+ *
+ * @returns true if the view initialized, false if it settled on an error
+ */
+export async function whenViewSettled(view) {
+    await when(() => view.initialized || !!view.error);
+    return view.initialized;
+}

package/esm/util/withFeatureDetails.d.ts

@@ -0,0 +1,34 @@
+import type { Feature } from './simpleFeature.ts';
+import type { IStateTreeNode } from '@jbrowse/mobx-state-tree';
+/**
+ * Run `onFeat` on the feature a details lookup answers with, and say something
+ * when it answers with nothing.
+ *
+ * Every display paints from slim render arrays and re-fetches the whole feature
+ * on demand, so "click a feature, open its details" is always a round trip that
+ * can come back empty. Six call sites across three plugins had written that
+ * round trip out, and the shape they shared was
+ * `if (feature && isAlive(self)) { … }` — a guard that reads as defensive and is
+ * really the whole of what a click does when the lookup fails. Five of the six
+ * did nothing at all, which is the worst answer to a click: the user cannot tell
+ * a missing feature from a dead menu item.
+ *
+ * **The three outcomes are separated here because only here can they be told
+ * apart**, and conflating any two of them is a bug this replaces:
+ *
+ * - **threw** — reported with its own reason, through `notifyError`. A `fetch`
+ *   passed in must therefore let its errors out; one that catches and answers
+ *   `undefined` turns its failure into the miss below, and the user is told off
+ *   twice for one click, the second time less usefully.
+ * - **answered nothing** — `onMiss`, which defaults to the shared sentence.
+ * - **the node died mid-flight** — nothing but the console. A track can be
+ *   unticked while the fetch is in flight, and every branch below reaches
+ *   `getSession(self)`, which throws on a detached node — inside a floating
+ *   promise, where nothing catches it.
+ *
+ * `onMiss` is a parameter rather than fixed because one caller legitimately
+ * stays quiet: the pileup pre-warms the read behind a context menu before the
+ * user has asked for anything, so a miss there just leaves the menu without its
+ * feature items. Passing `() => {}` is how a call site says it is speculative.
+ */
+export declare function withFeatureDetails(self: IStateTreeNode, fetch: () => Promise<Feature | undefined>, onFeat: (feat: Feature) => void, onMiss?: () => void): Promise<void>;

package/esm/util/withFeatureDetails.js

@@ -0,0 +1,59 @@
+import { isAlive } from '@jbrowse/mobx-state-tree';
+import { notifyFeatureDetailsMiss } from './openFeatureWidget.js';
+import { getNotificationSink } from './sessionServices.js';
+/**
+ * Run `onFeat` on the feature a details lookup answers with, and say something
+ * when it answers with nothing.
+ *
+ * Every display paints from slim render arrays and re-fetches the whole feature
+ * on demand, so "click a feature, open its details" is always a round trip that
+ * can come back empty. Six call sites across three plugins had written that
+ * round trip out, and the shape they shared was
+ * `if (feature && isAlive(self)) { … }` — a guard that reads as defensive and is
+ * really the whole of what a click does when the lookup fails. Five of the six
+ * did nothing at all, which is the worst answer to a click: the user cannot tell
+ * a missing feature from a dead menu item.
+ *
+ * **The three outcomes are separated here because only here can they be told
+ * apart**, and conflating any two of them is a bug this replaces:
+ *
+ * - **threw** — reported with its own reason, through `notifyError`. A `fetch`
+ *   passed in must therefore let its errors out; one that catches and answers
+ *   `undefined` turns its failure into the miss below, and the user is told off
+ *   twice for one click, the second time less usefully.
+ * - **answered nothing** — `onMiss`, which defaults to the shared sentence.
+ * - **the node died mid-flight** — nothing but the console. A track can be
+ *   unticked while the fetch is in flight, and every branch below reaches
+ *   `getSession(self)`, which throws on a detached node — inside a floating
+ *   promise, where nothing catches it.
+ *
+ * `onMiss` is a parameter rather than fixed because one caller legitimately
+ * stays quiet: the pileup pre-warms the read behind a context menu before the
+ * user has asked for anything, so a miss there just leaves the menu without its
+ * feature items. Passing `() => {}` is how a call site says it is speculative.
+ */
+export async function withFeatureDetails(self, fetch, onFeat, onMiss = () => {
+    notifyFeatureDetailsMiss(self);
+}) {
+    try {
+        const feature = await fetch();
+        if (!isAlive(self)) {
+            return;
+        }
+        if (feature) {
+            onFeat(feature);
+        }
+        else {
+            onMiss();
+        }
+    }
+    catch (e) {
+        // Logged whatever happened, and only toasted while the display is still
+        // there: `getSession` throws on a detached node, and a message naming a
+        // track the user has already closed is noise they cannot act on.
+        console.error(e);
+        if (isAlive(self)) {
+            getNotificationSink(self).notifyError(`${e}`, e);
+        }
+    }
+}