@jbrowse/core 4.2.1 → 5.0.0-beta.1

package/esm/util/useRowVirtualScroll.js

@@ -0,0 +1,63 @@
+import { applyRowResizeWheel } from './applyRowResizeWheel.js';
+import { useVirtualScrollWheel } from './useVirtualScrollWheel.js';
+/**
+ * Wheel gestures over a **row-stack** panel — the multi-sample variant displays
+ * and MAF: `shift`+wheel resizes the rows (a vertical-zoom that keeps the row
+ * under the cursor put), a plain wheel scrolls them, and anything the panel
+ * can't consume is left to bubble to the view.
+ *
+ * These panels paint a fixed-size canvas at `-scrollTop` rather than living in a
+ * DOM overflow container, so nothing scrolls them without this.
+ *
+ * ADR-027 keeps wheel-*intent* dispatch per handler, because the four panels do
+ * not agree on what a gesture means — and that still holds. This is the one rule
+ * two of them genuinely share, which the ADR states outright ("same rule as the
+ * variant displays, and deliberately so: same sample-row shape, same coupled
+ * row-height axis"). It is unified for exactly that reason, and no further: the
+ * pileup / canvas-basic rule (`shift` scrolls, nothing resizes) stays where it
+ * is. `scrollZoom` and `viewportHeight` are inputs rather than reads off the
+ * model, so core needs no view typing and each display keeps naming its own
+ * rows-area height.
+ */
+export function useRowVirtualScroll(el, model, { viewportHeight, scrollZoom, }) {
+    useVirtualScrollWheel(el, (e, applyScroll, rowsEl) => {
+        // ctrl/meta is the browser's own zoom (and the view's pinch-zoom) and is
+        // never ours, whatever else is held. Tested first rather than only in the
+        // scroll branch: ctrl+shift+wheel used to reach the resize below, which
+        // `preventDefault`s — so a row-stack display swallowed page zoom where
+        // every other display passes it through.
+        if (e.ctrlKey || e.metaKey) {
+            return;
+        }
+        if (e.shiftKey) {
+            // Resizing exits fit-to-height into a pinned height, which is what makes
+            // the gesture meaningful: the fit height is exactly the floor it shrinks
+            // to, so there is nothing to zoom while the sentinel is set.
+            applyRowResizeWheel(e, rowsEl, {
+                effectiveRowHeight: model.effectiveRowHeight,
+                scrollTop: model.scrollTop,
+                nrow: model.nrow,
+                viewportHeight,
+                setRowHeight: n => {
+                    model.setRowHeight(n);
+                },
+                setScrollTop: n => {
+                    model.setScrollTop(n);
+                },
+            });
+        }
+        else if (!scrollZoom) {
+            // A gesture the panel can't consume is left alone: with the rows fitting
+            // the track (`scrollableHeight === 0`, always true in fit-to-height mode)
+            // the wheel reaches the view and zooms or scrolls the page exactly as it
+            // does over any other track. Same for the explicit zoom gestures.
+            applyScroll(e, {
+                scrollTop: model.scrollTop,
+                viewportHeight,
+                scrollableHeight: model.scrollableHeight,
+            }, n => {
+                model.setScrollTop(n);
+            });
+        }
+    });
+}

package/esm/util/useVirtualScrollWheel.d.ts

@@ -0,0 +1,7 @@
+export interface VirtualScrollOpts {
+    scrollTop: number;
+    viewportHeight: number;
+    scrollableHeight: number;
+}
+export type ApplyVirtualScroll = (e: WheelEvent, opts: VirtualScrollOpts, commit: (scrollTop: number) => void) => void;
+export declare function useVirtualScrollWheel(panel: HTMLElement | null, onWheel: (e: WheelEvent, applyScroll: ApplyVirtualScroll, el: HTMLElement) => void): void;

package/esm/util/useVirtualScrollWheel.js

@@ -0,0 +1,108 @@
+import { useCallback, useEffect, useMemo, useRef } from 'react';
+import { createFrameCoalescer } from './frameCoalescer.js';
+import { trackPointerPresence } from './pointerPresence.js';
+import { createScrollLatch } from './scrollLatch.js';
+import { useEventCallback } from './useEventCallback.js';
+import { normalizeWheelDelta } from './wheelZoom.js';
+// Whether the wheel landed inside something within the panel that runs its own
+// gestures — JBrowse's `[data-gesture-owner]` marker, the same one the LGV's
+// click-drag pan and MAF's drag-selection test for. A panel spans its overlays
+// now, and a few of those are controls rather than content: the display's own
+// `VerticalScrollbar` (which scrolls the panel itself, from its own listener),
+// the pileup's band resize handles, a floating legend. Those keep the gesture
+// they already had instead of being absorbed the moment the panel grew to cover
+// them.
+//
+// The marker element ITSELF is a panel at the one call site that is one — the
+// scrollbar binds this hook to its own marked track — so an owner that IS the
+// panel does not count. Nor does one ABOVE it: `TrackContainer` stamps the
+// marker once for its whole overlay layer, and `closest` walking out of the
+// panel into that would otherwise disown every wheel a display gets.
+function claimedInside(panel, target) {
+    const owner = target instanceof Element ? target.closest('[data-gesture-owner]') : null;
+    return owner !== null && owner !== panel && panel.contains(owner);
+}
+// Non-passive wheel wiring for a canvas-backed virtual scroll (no DOM overflow
+// container to self-correct). Owns the latch, the per-frame coalescing, and the
+// listener lifecycle, and hands the caller an `applyScroll` that runs the latch
+// + schedules the commit. The gesture guards (scrollZoom, ctrl/meta,
+// shift-to-resize) differ per display and so stay in the caller; this
+// centralizes the mechanical latch + listener + rAF boilerplate shared by the
+// alignments pileup, the variant matrix, and the canvas display.
+//
+// **Bind this to the panel, not to the `<canvas>`.** A canvas cannot hold DOM
+// children, so every overlay a display draws over it — floating feature labels,
+// group chips, sashimi arcs — is a positioned SIBLING, and the ones that answer
+// the pointer (`pointerEvents: 'auto'`, because they are clickable) are what a
+// wheel event over them targets. That event bubbles past the canvas entirely, so
+// a listener bound to the canvas never sees it and the gesture falls through to
+// the page mid-scroll. Bound to the element containing both, the wheel is the
+// panel's wherever inside it the cursor happens to be. `trackPointerPresence`
+// below keys off the same element, and `mouseenter`/`mouseleave` ignore
+// descendant transitions — so crossing onto an overlay no longer reads as
+// leaving the panel either.
+//
+// What keeps a panel safe to widen is `claimedInside` above: it covers its
+// overlays, and yields the ones that run gestures of their own.
+export function useVirtualScrollWheel(panel, 
+// `el` is the element the listener is bound to, handed back non-null: a
+// gesture measuring against its own box (the row-resize pin) would otherwise
+// re-assert the nullable it was passed, at the one call site that cannot be
+// reached with a null.
+onWheel) {
+    const latch = useMemo(() => createScrollLatch(), []);
+    const frame = useMemo(() => createFrameCoalescer(), []);
+    // The latched scroll position as it advances across one frame's events. The
+    // latch reads this, not the model, so its boundary/preventDefault decision
+    // sees monotonically advancing offsets and no delta is lost to a
+    // not-yet-committed model read.
+    const runningRef = useRef(0);
+    const applyScroll = useCallback((e, { scrollTop, viewportHeight, scrollableHeight }, commit) => {
+        if (scrollableHeight <= 0) {
+            return;
+        }
+        // A fresh frame (nothing pending) re-syncs to the model's live scrollTop;
+        // within a frame `running` keeps advancing from the last latched offset.
+        if (!frame.pending) {
+            runningRef.current = scrollTop;
+        }
+        const dy = normalizeWheelDelta(e.deltaY, e.deltaMode, viewportHeight);
+        const next = latch.scroll(e, runningRef.current, dy, scrollableHeight);
+        if (next !== null) {
+            runningRef.current = next;
+            // The first move of a frame schedules the commit; later moves only
+            // advance `running`, so the frame ends with a single setScrollTop (one
+            // repaint) carrying the accumulated offset.
+            frame.schedule(() => {
+                commit(runningRef.current);
+            });
+        }
+    }, [latch, frame]);
+    const handleWheel = useEventCallback((e, el) => {
+        onWheel(e, applyScroll, el);
+    });
+    useEffect(() => {
+        if (!panel) {
+            return undefined;
+        }
+        // Ignore wheel events the browser keeps latching to this panel once the
+        // pointer has left (see trackPointerPresence): let them chain to the page
+        // and reset the latch so the next in-panel gesture starts clean. Without
+        // this the panel stays stuck to per-track scroll after the mouse has left —
+        // worst in embedded, where the outer page is the thing that should scroll.
+        const presence = trackPointerPresence(panel, () => {
+            latch.reset();
+        });
+        const onWheelNative = (e) => {
+            if (presence.isOver && !claimedInside(panel, e.target)) {
+                handleWheel(e, panel);
+            }
+        };
+        panel.addEventListener('wheel', onWheelNative, { passive: false });
+        return () => {
+            panel.removeEventListener('wheel', onWheelNative);
+            presence.dispose();
+            frame.cancel();
+        };
+    }, [panel, handleWheel, latch, frame]);
+}

package/esm/util/viewStatus.d.ts

@@ -0,0 +1,58 @@
+/**
+ * The mutually-exclusive lifecycle state of a view, as one value.
+ *
+ * A view answers this question through nine getters today — `ready`, `error`,
+ * `initialized`, `showLoading`, `showImportForm`, `hasSomethingToShow`,
+ * `loadingMessage`, `loadingProgress`, `assemblyErrors` — and a host reading
+ * them has to re-derive the precedence by subtraction, which is the mistake
+ * `computeDisplayPhase` was written to stop one level down. `view.ready` **is**
+ * that subtraction: `!showLoading && !this.error`.
+ *
+ * The payload travels with the branch, so a caller cannot read a loading
+ * message out of a failed view or an error out of a healthy one.
+ */
+export type ViewStatus = {
+    type: 'ready';
+} | {
+    type: 'error';
+    error: unknown;
+} | {
+    type: 'loading';
+    message: string;
+    progress: number | undefined;
+} | {
+    type: 'noRegions';
+};
+export interface ViewStatusInputs {
+    error: unknown;
+    /**
+     * Whether anything has told the view where to look — displayed regions, or an
+     * `init` blob still being applied.
+     */
+    hasSomethingToShow: boolean;
+    /**
+     * The view's own loading term, as a thunk: `undefined` when it is not
+     * loading, otherwise what the spinner should say.
+     *
+     * A thunk for the same reason `computeDisplayPhase` takes one. The message
+     * and the progress fraction come off the assembly's download status, which
+     * ticks continuously while a file is in flight — so evaluating it eagerly
+     * would make every reader of a *ready* view subscribe to a churning
+     * observable it never displays.
+     */
+    loading: () => {
+        message: string;
+        progress: number | undefined;
+    } | undefined;
+}
+/**
+ * Precedence is `error` > `noRegions` > `loading` > `ready`, in one place,
+ * rather than re-encoded by subtraction in each view and again in each host.
+ *
+ * **`ready` here is strictly narrower than `view.ready`**, which is the point of
+ * having it. That getter is true when nothing has told the view where to look —
+ * `showLoading` is false in that state and so is `error` — so a host gating on
+ * it mounts track components over a view with no regions and gets an empty box
+ * with nothing anywhere saying why. `noRegions` is that state, named.
+ */
+export declare function computeViewStatus({ error, hasSomethingToShow, loading, }: ViewStatusInputs): ViewStatus;

package/esm/util/viewStatus.js

@@ -0,0 +1,20 @@
+/**
+ * Precedence is `error` > `noRegions` > `loading` > `ready`, in one place,
+ * rather than re-encoded by subtraction in each view and again in each host.
+ *
+ * **`ready` here is strictly narrower than `view.ready`**, which is the point of
+ * having it. That getter is true when nothing has told the view where to look —
+ * `showLoading` is false in that state and so is `error` — so a host gating on
+ * it mounts track components over a view with no regions and gets an empty box
+ * with nothing anywhere saying why. `noRegions` is that state, named.
+ */
+export function computeViewStatus({ error, hasSomethingToShow, loading, }) {
+    if (error) {
+        return { type: 'error', error };
+    }
+    if (!hasSomethingToShow) {
+        return { type: 'noRegions' };
+    }
+    const pending = loading();
+    return pending ? { type: 'loading', ...pending } : { type: 'ready' };
+}

package/esm/util/virtualRange.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Index window for a virtualized 1-D axis of uniform cells: the `[start, end)`
+ * range covering the visible span plus `overscan` cells of buffer on each side,
+ * clamped to `[0, total]`.
+ *
+ * `end` is anchored to `start` (a fixed cell count) rather than recomputed from
+ * `scroll + viewport`. That makes the window **stable across sub-cell scrolling**
+ * — it only moves when `start` crosses a cell boundary — which is what lets
+ * consumers skip work on most scroll events: a canvas keeps its size and
+ * contents, a DOM list keeps its rows mounted. Recomputing `end` independently
+ * is tighter by up to `overscan` cells at the origin and costs that stability,
+ * which is the wrong trade for both.
+ *
+ * `start` is clamped to `total`, not just to 0. A list that shrinks while its
+ * container keeps its scroll position (a new region or track arriving under a
+ * scrolled grid) otherwise yields `start > end` — an inverted range whose
+ * consumers compute a negative canvas height and paint nothing until the next
+ * scroll event. The faceted selector had already hit that and clamped for it;
+ * the MAF sequence grid had the same math without the clamp, which is what
+ * brought the two together here.
+ */
+export declare function virtualRange({ scroll, cellSize, viewport, overscan, total, }: {
+    /** scroll offset of the container, in px */
+    scroll: number;
+    /** px size of one cell along this axis */
+    cellSize: number;
+    /** px size of the visible span */
+    viewport: number;
+    /** cells of buffer to render beyond each edge */
+    overscan: number;
+    /** total number of cells on this axis */
+    total: number;
+}): {
+    start: number;
+    end: number;
+};

package/esm/util/virtualRange.js

@@ -0,0 +1,26 @@
+/**
+ * Index window for a virtualized 1-D axis of uniform cells: the `[start, end)`
+ * range covering the visible span plus `overscan` cells of buffer on each side,
+ * clamped to `[0, total]`.
+ *
+ * `end` is anchored to `start` (a fixed cell count) rather than recomputed from
+ * `scroll + viewport`. That makes the window **stable across sub-cell scrolling**
+ * — it only moves when `start` crosses a cell boundary — which is what lets
+ * consumers skip work on most scroll events: a canvas keeps its size and
+ * contents, a DOM list keeps its rows mounted. Recomputing `end` independently
+ * is tighter by up to `overscan` cells at the origin and costs that stability,
+ * which is the wrong trade for both.
+ *
+ * `start` is clamped to `total`, not just to 0. A list that shrinks while its
+ * container keeps its scroll position (a new region or track arriving under a
+ * scrolled grid) otherwise yields `start > end` — an inverted range whose
+ * consumers compute a negative canvas height and paint nothing until the next
+ * scroll event. The faceted selector had already hit that and clamped for it;
+ * the MAF sequence grid had the same math without the clamp, which is what
+ * brought the two together here.
+ */
+export function virtualRange({ scroll, cellSize, viewport, overscan, total, }) {
+    const start = Math.min(total, Math.max(0, Math.floor(scroll / cellSize) - overscan));
+    const visible = Math.ceil(viewport / cellSize) + overscan * 2;
+    return { start, end: Math.min(total, start + visible) };
+}

package/esm/util/webStorage.d.ts

@@ -0,0 +1,26 @@
+export interface GuardedStorage {
+    /**
+     * Whether there is a store to persist to at all — the first two failures
+     * above, both of which are decided once for the page.
+     *
+     * Every accessor is safe without asking; what this answers is the different
+     * question of whether persistence is *real*. With no store, a write is
+     * dropped and the matching read answers the default, so a caller that
+     * round-trips a value through a key (rather than merely saving one) has to
+     * know, or it reads back its own default and calls it the stored value.
+     */
+    available: () => boolean;
+    /** The raw string stored at `key`, or undefined if absent or unreadable. */
+    getItem: (key: string) => string | undefined;
+    /**
+     * Returns whether the store took the value. Nearly every caller ignores that
+     * — a setting that could not be persisted is not worth interrupting anyone
+     * over — but a caller that reads the key back to learn the current value
+     * needs to know that the read will not reflect this write.
+     */
+    setItem: (key: string, value: string) => boolean;
+    /** Returns whether the store took the removal; see {@link setItem}. */
+    removeItem: (key: string) => boolean;
+}
+export declare const guardedLocalStorage: GuardedStorage;
+export declare const guardedSessionStorage: GuardedStorage;

package/esm/util/webStorage.js

@@ -0,0 +1,92 @@
+// The guard both Web Storage stores need, written once.
+//
+// Every accessor built here is *total*: it falls back rather than throwing.
+// That is not defensiveness for its own sake — the callers are MobX autoruns
+// persisting a setting and state-model actions caching a token, and there a
+// throw is doubly bad. It skips the writes queued behind it in the same autorun
+// body (the LGV persists six keys in a row, the hierarchical track selector
+// seven), and MobX reports it as an uncaught reaction error on every subsequent
+// tick.
+//
+// Three separate ways this can fail, and only the first is the obvious one:
+//
+// - no store global at all — an RPC worker, SSR.
+// - reading the global THROWS rather than being undefined: a cross-origin
+//   iframe with third-party storage blocked, or Safari with cookies disabled.
+//   `typeof localStorage` invokes the same getter, so even the probe has to be
+//   guarded — which is also why a `typeof … === 'undefined'` probe is not a way
+//   to ask whether you are in a worker. This is the embedded-product case
+//   (`@jbrowse/react-*` on someone else's page), where it is also the least
+//   likely to be noticed by us.
+// - the store exists and reads fine, but `setItem` throws: quota exhausted, or
+//   Safari private browsing, which refuses every write.
+/**
+ * `read` names the global rather than being handed it, so resolving it can be
+ * deferred past module load and wrapped in the try that the read itself needs.
+ * `label` only ever reaches the one warning below.
+ */
+function guardedStorage(read, label) {
+    // Resolved once. `null` means "checked, unavailable" — distinct from the
+    // `undefined` that means "not checked yet".
+    let store;
+    function getStore() {
+        if (store === undefined) {
+            try {
+                store = read();
+            }
+            catch {
+                store = null;
+            }
+        }
+        return store ?? undefined;
+    }
+    // One warning per page per store, not one per failed write: the autoruns that
+    // persist settings re-run on every change, so a persistent failure (quota,
+    // private browsing) would otherwise fill the console with the same line. Same
+    // doctrine as the `savingFailed` latch in jbrowse-web's session autosave.
+    let warnedOnWrite = false;
+    return {
+        available: () => getStore() !== undefined,
+        getItem(key) {
+            try {
+                return getStore()?.getItem(key) ?? undefined;
+            }
+            catch {
+                return undefined;
+            }
+        },
+        setItem(key, value) {
+            const s = getStore();
+            if (!s) {
+                return false;
+            }
+            try {
+                s.setItem(key, value);
+                return true;
+            }
+            catch (e) {
+                if (!warnedOnWrite) {
+                    warnedOnWrite = true;
+                    console.warn(`Unable to persist to ${label} (key "${key}"); further failures are not reported`, e);
+                }
+                return false;
+            }
+        },
+        removeItem(key) {
+            const s = getStore();
+            if (!s) {
+                return false;
+            }
+            try {
+                s.removeItem(key);
+                return true;
+            }
+            catch {
+                // nothing useful to do: the value we wanted gone is unreachable anyway
+                return false;
+            }
+        },
+    };
+}
+export const guardedLocalStorage = guardedStorage(() => localStorage, 'localStorage');
+export const guardedSessionStorage = guardedStorage(() => sessionStorage, 'sessionStorage');

package/esm/util/wheelZoom.d.ts

@@ -0,0 +1,59 @@
+export declare const MAX_ZOOM_RATE_PER_MS: number;
+export declare const SCROLL_ZOOM_FACTOR_DIVISOR = 500;
+export declare function wheelZoomAccum(normalizedDeltaY: number, isCtrlZoom: boolean): number;
+export declare function getZoomNormalizer(deltaY: number): 25 | 75 | 150 | 500;
+export declare function normalizeWheelDelta(delta: number, deltaMode: number, pageHeight?: number): number;
+export declare function wheelFrameElapsedMs(now: number, lastRafTime: number | null): number;
+export declare function accumulateScroll(prev: number, deltaX: number): number;
+export declare const ZOOM_ACTIVE_WINDOW_MS = 100;
+export declare function isActivelyZooming(now: number, lastZoomTime: number | null): boolean;
+export declare function applyZoomAccum(bpPerPx: number, zoomAccum: number, elapsedMs: number): number;
+export interface WheelZoomView {
+    bpPerPx: number;
+    zoomTo: (bpPerPx: number, offset?: number) => void;
+    horizontalScroll: (delta: number) => void;
+}
+export interface WheelZoomTarget {
+    views: WheelZoomView[];
+    scrollZoom: boolean;
+    originElement: () => HTMLElement | undefined;
+}
+export interface WheelZoomControllerOptions {
+    element: HTMLElement;
+    resolveTarget: (event: WheelEvent) => WheelZoomTarget | undefined;
+    swallowUnhandled?: boolean;
+    /**
+     * Abandon the gesture once the pointer leaves `element`, rather than following
+     * the wheel events the browser keeps latching here (see trackPointerPresence).
+     *
+     * Only for an element large and stationary enough that "the pointer left" is a
+     * real exit. On a small or moving target it isn't: a zoom slides a thin svg
+     * ribbon out from under a stationary cursor, the browser fires mouseleave, and
+     * the gesture would die halfway through. So this is opt-in, not the default.
+     */
+    releaseOnPointerLeave?: boolean;
+    onEvent?: (event: WheelEvent) => void;
+}
+/**
+ * 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 declare function createWheelZoomController({ element, resolveTarget, swallowUnhandled, releaseOnPointerLeave, onEvent, }: WheelZoomControllerOptions): () => void;