@jbrowse/core 4.3.0 → 5.0.0-beta.1

package/esm/util/useFeatureSequence.d.ts

@@ -1,19 +1,25 @@
-import type { AbstractSessionModel, Feature } from './index.ts';
-export declare function useFeatureSequence({ session, feature, upDownBp, forceLoad, assemblyName, shouldFetch, }: {
-    assemblyName: string;
+import type { AbstractSessionModel } from './types/index.ts';
+export declare function useFeatureSequence({ session, start, end, refName, upDownBp, forceLoad, assemblyName, }: {
+    assemblyName: string | undefined;
     session?: AbstractSessionModel;
-    feature: Feature;
+    start: number;
+    end: number;
+    refName: string;
     upDownBp: number;
     forceLoad: boolean;
-    shouldFetch?: boolean;
 }): {
     sequence: {
+        error: string;
+        seq?: undefined;
+        upstream?: undefined;
+        downstream?: undefined;
+    } | {
+        error?: undefined;
         seq: string;
         upstream: string;
         downstream: string;
-    } | {
-        error: string;
     } | undefined;
     loading: boolean;
     error: unknown;
+    status: import("./progress.ts").RpcStatus | undefined;
 };

package/esm/util/useFeatureSequence.js

@@ -1,87 +1,65 @@
-import { useEffect, useMemo, useState } from 'react';
-import { fetchSeq } from "./fetchSeq.js";
+import { fetchSeq } from './fetchSeq.js';
+import { createStatusFanOut } from './progress.js';
+import { useFetch } from './useFetch.js';
 const BPLIMIT = 20_000_000;
-export function useFeatureSequence({ session, feature, upDownBp, forceLoad, assemblyName, shouldFetch = true, }) {
-    const [sequence, setSequence] = useState();
-    const [error, setError] = useState();
-    const [loading, setLoading] = useState(false);
-    const key = useMemo(() => {
-        if (!session || !shouldFetch) {
-            return null;
-        }
-        const start = feature.get('start');
-        const end = feature.get('end');
-        const refName = feature.get('refName');
-        return {
+export function useFeatureSequence({ session, start, end, refName, upDownBp, forceLoad, assemblyName, }) {
+    const guard = session && assemblyName ? { session, assemblyName } : null;
+    const { data: sequence, error, isLoading: loading, status, } = useFetch(guard
+        ? [
+            'featureSequence',
+            guard.assemblyName,
+            refName,
             start,
             end,
-            refName,
-            assemblyName,
             upDownBp,
-            forceLoad,
-            sessionId: session.id || 'default',
-        };
-    }, [session, feature, assemblyName, upDownBp, forceLoad, shouldFetch]);
-    useEffect(() => {
-        if (!key) {
-            setSequence(undefined);
-            setError(undefined);
-            return;
-        }
-        ;
-        (async () => {
-            try {
-                setLoading(true);
-                setError(undefined);
-                const { start, end, refName, assemblyName, upDownBp, forceLoad } = key;
-                if (!forceLoad && end - start > BPLIMIT) {
-                    setSequence({
-                        error: `Genomic sequence larger than ${BPLIMIT}bp, use "force load" button to display`,
-                    });
-                    return;
-                }
-                const b = start - upDownBp;
-                const e = end + upDownBp;
-                const [seq, upstream, downstream] = await Promise.all([
-                    fetchSeq({
-                        start,
-                        end,
-                        refName,
-                        assemblyName,
-                        session: session,
-                    }),
-                    fetchSeq({
-                        start: Math.max(0, b),
+            +forceLoad,
+        ]
+        : null, guard
+        ? async (_name, _asm, _ref, _start, _end, _upDown, _force, stopToken, statusCallback) => {
+            const { session: s, assemblyName: asmName } = guard;
+            if (!forceLoad && end - start > BPLIMIT) {
+                return {
+                    error: `Genomic sequence larger than ${BPLIMIT}bp, use "force load" button to display`,
+                };
+            }
+            // three concurrent reads sharing one status field, so each gets its
+            // own slot and they aggregate into one bar
+            const slot = createStatusFanOut(statusCallback);
+            const [seq, upstream, downstream] = await Promise.all([
+                fetchSeq({
+                    start,
+                    end,
+                    refName,
+                    assemblyName: asmName,
+                    session: s,
+                    stopToken,
+                    statusCallback: slot(),
+                }),
+                upDownBp > 0
+                    ? fetchSeq({
+                        start: Math.max(0, start - upDownBp),
                         end: start,
                         refName,
-                        assemblyName,
-                        session: session,
-                    }),
-                    fetchSeq({
+                        assemblyName: asmName,
+                        session: s,
+                        stopToken,
+                        statusCallback: slot(),
+                    })
+                    : Promise.resolve(''),
+                upDownBp > 0
+                    ? fetchSeq({
                         start: end,
-                        end: e,
+                        end: end + upDownBp,
                         refName,
-                        assemblyName,
-                        session: session,
-                    }),
-                ]);
-                setSequence({
-                    seq,
-                    upstream,
-                    downstream,
-                });
-            }
-            catch (err) {
-                setError(err);
-            }
-            finally {
-                setLoading(false);
-            }
-        })();
-    }, [key, session]);
-    return {
-        sequence,
-        loading,
-        error,
-    };
+                        assemblyName: asmName,
+                        session: s,
+                        stopToken,
+                        statusCallback: slot(),
+                    })
+                    : Promise.resolve(''),
+            ]);
+            return { seq, upstream, downstream };
+        }
+        : null);
+    return { sequence, loading, error, status };
 }

package/esm/util/useFetch.d.ts

@@ -0,0 +1,56 @@
+import type { RpcStatus, StatusCallback } from './progress.ts';
+import type { StopToken } from './stopToken.ts';
+export type FetchKey = string | readonly unknown[] | null | undefined | false;
+type FetchingKey<Key> = Exclude<Key, null | undefined | false>;
+/**
+ * The fetcher's parameter list, derived from the key. An array key is spread
+ * into the parameters, so a tuple key gives the fetcher one typed parameter per
+ * element (`MafSequenceWidget` destructures its key that way, to reuse the
+ * narrowing the null-key ternary already did); a string key arrives as the
+ * single argument (`useGenomesData`). Most fetchers close over what they need
+ * and declare no parameters at all, which stays assignable either way.
+ *
+ * A stop token and a status callback follow the key arguments. The token is
+ * created per fetch and stopped when the key changes or the component unmounts,
+ * so a fetcher that forwards it to an RPC cancels the worker instead of leaving
+ * it grinding on an answer nobody is waiting for. The callback is what the RPC's
+ * own progress comes back through, and it surfaces on the hook's `status` — a
+ * dialog that forwards both gets "Downloading features 42%" and a cancel that
+ * works, instead of a bare spinner over an uninterruptible whole-chromosome
+ * read. Fetchers that take neither are unaffected.
+ */
+type FetcherArgs<Key> = FetchingKey<Key> extends readonly unknown[] ? [...FetchingKey<Key>, StopToken, StatusCallback] : [FetchingKey<Key>, StopToken, StatusCallback];
+interface FetchState<Data> {
+    data: Data | undefined;
+    error: unknown;
+    isLoading: boolean;
+}
+interface UseFetchOptions<Data> {
+    onError?: (error: unknown) => void;
+    onSuccess?: (data: Data) => void;
+}
+interface UseFetchResponse<Data> extends FetchState<Data> {
+    /**
+     * Trigger a refetch. Returns nothing: the result arrives through
+     * `data`/`error`/`isLoading` like the initial fetch, and a promise here could
+     * only resolve before the refetch it schedules had run.
+     */
+    mutate: () => void;
+    isValidating: boolean;
+    /**
+     * Latest progress the in-flight fetcher reported through its status callback,
+     * or undefined when it reported none or the fetch has settled. Render it with
+     * `statusProgressLabel` (and `statusFraction` for a bar); a fetcher that never
+     * calls its callback leaves this undefined and the consumer shows whatever it
+     * showed before.
+     */
+    status: RpcStatus | undefined;
+}
+/**
+ * Revalidate every mounted `useFetch` on this key. Synchronous for the same
+ * reason the per-hook `mutate` is: it schedules the refetches, and each hook
+ * reports its own result through the state it already exposes.
+ */
+export declare function mutate(key: FetchKey): void;
+export declare function useFetch<Data = unknown, Key extends FetchKey = FetchKey>(key: Key, fetcher: ((...args: FetcherArgs<Key>) => Promise<Data>) | null, options?: UseFetchOptions<Data>): UseFetchResponse<Data>;
+export {};

package/esm/util/useFetch.js

@@ -0,0 +1,188 @@
+import { useCallback, useEffect, useRef, useState } from 'react';
+import { createStatusWindow } from './progress.js';
+import { createStopToken, stopStopToken } from './stopToken.js';
+const isNil = (k) => k === null || k === undefined || k === false;
+// A null result means "don't fetch": no key, or an array key with a missing
+// piece (e.g. an offset that isn't resolved yet).
+function serializeKey(key) {
+    return isNil(key) || (Array.isArray(key) && key.some(isNil))
+        ? null
+        : JSON.stringify(key);
+}
+// Cross-component refetch coordination, keyed by serialized key. Holds only
+// refetch callbacks (never data), so there is no global cache to go stale —
+// this is the one SWR feature we relied on: mutate(key) revalidates every
+// mounted useFetch sharing that key.
+const listeners = new Map();
+/**
+ * Revalidate every mounted `useFetch` on this key. Synchronous for the same
+ * reason the per-hook `mutate` is: it schedules the refetches, and each hook
+ * reports its own result through the state it already exposes.
+ */
+export function mutate(key) {
+    const serialized = serializeKey(key);
+    if (serialized) {
+        for (const refetch of listeners.get(serialized) ?? []) {
+            refetch();
+        }
+    }
+}
+export function useFetch(key, fetcher, options = {}) {
+    const serialized = serializeKey(key);
+    // A null fetcher is the second way to say "don't fetch", so its nullness is a
+    // fetch input exactly like the key is — the effect below has to re-run when it
+    // flips. Only the boolean can go in the dependency list: the fetcher itself is
+    // usually an inline closure, so depending on its identity would refetch every
+    // render. Tracked separately from the key because the two are independent —
+    // gating on the key alone leaves a `fetcher` that resolves from null to a real
+    // function (an adapter/config arriving late) permanently stuck not fetching.
+    const hasFetcher = fetcher !== null;
+    const [state, setState] = useState(() => ({
+        data: undefined,
+        error: undefined,
+        // seeded from the key rather than starting false: the effect below runs
+        // after the first paint, so a false seed showed the resolved-and-empty state
+        // for a frame before the spinner (an empty attribute table, an empty list)
+        isLoading: serialized !== null && hasFetcher,
+    }));
+    // bumped to force a refetch (local mutate() or a cross-component mutate(key))
+    const [nonce, setNonce] = useState(0);
+    // separate from `state` because it moves on its own cadence: the RPC status
+    // stream ticks throughout one fetch, while data/error/isLoading move once
+    const [status, setStatus] = useState(undefined);
+    // refs let the fetch effect depend only on the serialized key + nonce without
+    // re-running when the (often inline) fetcher/options/key identities change
+    const optionsRef = useRef(options);
+    optionsRef.current = options;
+    const fetcherRef = useRef(fetcher);
+    fetcherRef.current = fetcher;
+    const keyRef = useRef(key);
+    keyRef.current = key;
+    // the key the last fetch ran under, to tell a mutate()-driven refetch from a
+    // key change — see the setState below
+    const fetchedKeyRef = useRef(null);
+    useEffect(() => {
+        const key = keyRef.current;
+        const fetcher = fetcherRef.current;
+        if (serialized === null || !fetcher) {
+            // when the key becomes null, callers see undefined data again rather
+            // than the prior fetch's result
+            fetchedKeyRef.current = null;
+            setState({ data: undefined, error: undefined, isLoading: false });
+            // and the same for the progress, which otherwise sticks: a key going nil
+            // *during* a fetch runs this branch's cleanup first, so the `alive` guard
+            // on the settle below has already closed and nothing else clears it
+            setStatus(undefined);
+            return undefined;
+        }
+        else {
+            let alive = true;
+            // `alive` is about this effect run; `settled` is about this fetch. They
+            // differ for exactly one thing, the status stream below: an RPC resolves
+            // its status channel asynchronously, so a status can arrive after the
+            // fetch it describes has resolved — and without a second term it lands on
+            // top of the clear and sticks. (The trailing write queued *before* the
+            // fetch resolved is a different case, and the stream's own `clear` drops
+            // that one.)
+            let settled = false;
+            const stopToken = createStopToken();
+            // A refetch under the same key — mutate(), or the cross-component
+            // mutate(key) — is the same question asked again, so what is on screen is
+            // a stale answer to it rather than an answer to something else: leave it
+            // up and let `isLoading` say it is being rechecked. A key *change* still
+            // clears, because the old data describes a different question.
+            //
+            // Blanking on every refetch is what made the desktop start screen flash
+            // "No sessions available" after each rename, delete, or cancelled dialog.
+            // Consumers that want the old view gone during a revalidate already have
+            // it: they gate on `isLoading`, which is unchanged.
+            const sameKey = fetchedKeyRef.current === serialized;
+            fetchedKeyRef.current = serialized;
+            setState(prev => ({
+                data: sameKey ? prev.data : undefined,
+                error: undefined,
+                isLoading: true,
+            }));
+            // the previous fetch's last progress describes work that is over
+            setStatus(undefined);
+            // The runtime counterpart of FetcherArgs: an array key becomes one
+            // argument per element, anything else a single argument, then the stop
+            // token and the status callback. A conditional type over an unresolved
+            // `Key` can't be discharged
+            // inside the function body, so the parameter list is erased for this one
+            // call — callers still get the precise arity, and the looseness stops
+            // here.
+            const keyArgs = Array.isArray(key) ? key : [key];
+            // guarded and throttled for the same reason every other owner of a
+            // progress stream is: an RPC emits ~40 of these a second, and each one
+            // re-renders the dialog holding this hook
+            // one fetch is one stream, so the window is this effect run's
+            // the one writer, so the settle below clears through the same guard its
+            // statuses pass
+            const statusWindow = createStatusWindow(status => {
+                if (alive) {
+                    setStatus(status);
+                }
+            });
+            const { statusCallback, clear: clearStatus } = statusWindow.open({
+                isCurrent: () => alive && !settled,
+            });
+            const args = [...keyArgs, stopToken, statusCallback];
+            const call = fetcher;
+            Promise.resolve()
+                .then(() => call(...args))
+                .then(data => {
+                if (alive) {
+                    setState({ data, error: undefined, isLoading: false });
+                    optionsRef.current.onSuccess?.(data);
+                }
+            })
+                .catch((error) => {
+                if (alive) {
+                    setState({ data: undefined, error, isLoading: false });
+                    optionsRef.current.onError?.(error);
+                }
+            })
+                .finally(() => {
+                // however it settled, the progress it reported describes work that is
+                // over
+                settled = true;
+                clearStatus();
+            });
+            return () => {
+                alive = false;
+                // the token's lifetime is this fetch's. An abort rejection lands in the
+                // catch above with alive already false, so it never surfaces as an error
+                stopStopToken(stopToken);
+                // and the window's lifetime is too: `alive` already makes a queued
+                // trailing write a no-op, but the timer behind it would otherwise stand
+                // for up to a window past unmount
+                statusWindow.reset();
+            };
+        }
+    }, [serialized, hasFetcher, nonce]);
+    // register this instance so a cross-component mutate(key) can refetch it
+    useEffect(() => {
+        if (serialized === null) {
+            return undefined;
+        }
+        else {
+            const refetch = () => {
+                setNonce(n => n + 1);
+            };
+            const set = listeners.get(serialized) ?? new Set();
+            set.add(refetch);
+            listeners.set(serialized, set);
+            return () => {
+                set.delete(refetch);
+                if (set.size === 0) {
+                    listeners.delete(serialized);
+                }
+            };
+        }
+    }, [serialized]);
+    const mutate = useCallback(() => {
+        setNonce(n => n + 1);
+    }, []);
+    return { ...state, mutate, isValidating: state.isLoading, status };
+}

package/esm/util/useFetchPlugins.d.ts

@@ -0,0 +1,12 @@
+import type { JBrowsePlugin } from './types/data.ts';
+/**
+ * The plugin store listing. Shared by every surface that installs plugins (the
+ * in-session plugin store widget, Desktop's global plugins dialog) so they read
+ * the same manifest version and get the same integrity hashes and compatibility
+ * ranges — a second copy of this fetch is how one of them silently ends up on
+ * the unhashed v1 list.
+ */
+export declare function useFetchPlugins(): {
+    plugins: JBrowsePlugin[] | undefined;
+    error: unknown;
+};

package/esm/util/useFetchPlugins.js

@@ -0,0 +1,14 @@
+import { PLUGIN_STORE_URL } from '../checkPlugins.js';
+import { fetchJson } from './fetchJson.js';
+import { useFetch } from './useFetch.js';
+/**
+ * The plugin store listing. Shared by every surface that installs plugins (the
+ * in-session plugin store widget, Desktop's global plugins dialog) so they read
+ * the same manifest version and get the same integrity hashes and compatibility
+ * ranges — a second copy of this fetch is how one of them silently ends up on
+ * the unhashed v1 list.
+ */
+export function useFetchPlugins() {
+    const { data, error } = useFetch('jbrowse-plugin-store-v2', () => fetchJson(PLUGIN_STORE_URL));
+    return { plugins: data?.plugins, error };
+}

package/esm/util/useMeasure.d.ts

@@ -1,4 +1,14 @@
-export default function useMeasure(): readonly [import("react").RefObject<HTMLDivElement | null>, {
+/**
+ * Element size, via ResizeObserver.
+ *
+ * `track` names the axes the caller actually uses, and it is a performance knob
+ * as much as an API one: the observer fires for a change on *either* axis, so a
+ * width-only caller re-rendered every time its content grew taller. That is the
+ * common case in a view container, whose height follows its tracks. Naming the
+ * axis lets those updates be dropped instead. The unnamed axis is reported as
+ * `undefined` rather than a stale number, so nothing can quietly read it.
+ */
+export default function useMeasure(track?: 'both' | 'width' | 'height'): readonly [import("react").RefObject<HTMLDivElement | null>, {
     width?: number;
     height?: number;
 }];

package/esm/util/useMeasure.js

@@ -1,5 +1,15 @@
 import { useEffect, useRef, useState } from 'react';
-export default function useMeasure() {
+/**
+ * Element size, via ResizeObserver.
+ *
+ * `track` names the axes the caller actually uses, and it is a performance knob
+ * as much as an API one: the observer fires for a change on *either* axis, so a
+ * width-only caller re-rendered every time its content grew taller. That is the
+ * common case in a view container, whose height follows its tracks. Naming the
+ * axis lets those updates be dropped instead. The unnamed axis is reported as
+ * `undefined` rather than a stale number, so nothing can quietly read it.
+ */
+export default function useMeasure(track = 'both') {
     const ref = useRef(null);
     const [dims, setDims] = useState({
         width: undefined,
@@ -16,15 +26,19 @@ export default function useMeasure() {
             return;
         }
         const observer = new RS(entries => {
-            setDims({
-                width: entries[0].contentRect.width,
-                height: entries[0].contentRect.height,
-            });
+            const box = entries.at(-1)?.contentBoxSize[0];
+            if (box) {
+                const width = track === 'height' ? undefined : box.inlineSize;
+                const height = track === 'width' ? undefined : box.blockSize;
+                setDims(prev => prev.width === width && prev.height === height
+                    ? prev
+                    : { width, height });
+            }
         });
         observer.observe(ref.current);
         return () => {
             observer.disconnect();
         };
-    }, []);
+    }, [track]);
     return [ref, dims];
 }

package/esm/util/usePanZoom.d.ts

@@ -0,0 +1,75 @@
+import type { WheelZoomView } from './wheelZoom.ts';
+import type React from 'react';
+/**
+ * What the gestures need off a view: `bpPerPx`/`zoomTo`/`horizontalScroll` from
+ * WheelZoomView, plus the scroll-to-zoom preference.
+ *
+ * Duck-typed rather than taking a model, like the rest of the wheel-zoom layer.
+ *
+ * **`scrollZoom` belongs to the view, not to a piece of React state of your
+ * own.** Displays that scroll vertically inside themselves — an alignments
+ * pileup is the one you hit first — consult the same flag to decide whether the
+ * plain wheel is already spoken for, so a private copy that disagrees gets you
+ * both at once: the pileup scrolls its reads *and* the view zooms under the
+ * cursor. It is read at event time, so flipping it takes effect on the next
+ * wheel event with nothing rebound.
+ */
+export interface PanZoomView extends WheelZoomView {
+    scrollZoom?: boolean;
+}
+/**
+ * Wheel zoom and side-scroll, bound to `ref` for as long as the component
+ * lives.
+ *
+ * The listener is registered on the element directly and non-passively, which
+ * is not a style preference: React registers `wheel` at the root as a *passive*
+ * listener, so a handler installed through the `onWheel` prop cannot
+ * `preventDefault`, and the gesture would drive the page out from under you at
+ * the same time as it drove the view.
+ */
+export declare function useWheelZoom(ref: React.RefObject<HTMLElement | null>, view: PanZoomView): void;
+/**
+ * Every navigation gesture for a view, on one element: wheel zoom, side-scroll,
+ * and click-drag panning.
+ *
+ * ```tsx
+ * const ref = useWidthSetter(view)
+ * const { containerProps } = usePanZoom(ref, view)
+ * return (
+ *   <div ref={ref} {...containerProps}>
+ *     …tracks…
+ *   </div>
+ * )
+ * ```
+ *
+ * **`touch-action: none` comes with it**, written onto `ref`'s element. Without
+ * it a browser claims a touch drag as a page scroll, the pointer stream never
+ * arrives, and the gestures below are bound and dead — on a phone only, so a
+ * demo written and tested on a desktop is inert with nothing in the console.
+ * Asking the host for it was one line of documentation against a silent failure
+ * on half the devices there are.
+ *
+ * Set imperatively rather than handed back as a style, because a host that
+ * spreads its own `style` on the same element would drop it. React writes only
+ * the style properties its own `style` prop names, so this survives every
+ * render that does not mention `touchAction` — and a host that does name one
+ * wins, which is the escape hatch. `touchAction` here is the other:
+ * `'pan-y'` for a view inside a long document that should still scroll the
+ * page vertically, or `false` to leave the property alone entirely.
+ *
+ * JBrowse's own view splits these across two elements (the wheel on the whole
+ * view, the drag on the tracks area, so a drag over the header does nothing) and
+ * so binds `useWheelZoom` plus its own `useSideScroll`. One element is the
+ * normal case for an embedder, and this is it.
+ */
+export declare function usePanZoom(ref: React.RefObject<HTMLElement | null>, view: PanZoomView, { touchAction, }?: {
+    /** what to write as the element's `touch-action`, or false to write none */
+    touchAction?: React.CSSProperties['touchAction'] | false;
+}): {
+    containerProps: {
+        onPointerDown(event: React.PointerEvent<HTMLElement>): void;
+        onPointerMove(event: React.PointerEvent<HTMLElement>): void;
+        onPointerUp: (event: React.PointerEvent<HTMLElement>) => void;
+        onPointerCancel: (event: React.PointerEvent<HTMLElement>) => void;
+    };
+};