@jbrowse/core 4.3.0 → 5.0.0-beta.2

package/esm/util/unknownSnapshotKeys.js

@@ -0,0 +1,69 @@
+import { getType } from '@jbrowse/mobx-state-tree';
+import { getNotificationSink } from './sessionServices.js';
+/** what a diagnostic calls the view: its snapshot `type`, or the model name */
+export function viewLabel(self) {
+    return self.type ?? getType(self).name;
+}
+/**
+ * What every surface calls this mistake. A session spec launches a view without
+ * ever building a snapshot, so it classifies its own keys and reports them
+ * through its own session rather than through the sink below — one wording, so
+ * a typo reads the same whether it was written in a config or in a URL.
+ */
+export function unknownKeysMessage(label, keys) {
+    return `${label} ignored unknown key(s): ${keys.join(', ')}`;
+}
+/**
+ * Name the keys a view was handed and could not place, from the partition
+ * `withLaunchInput` runs on the snapshot.
+ */
+export function reportUnknownKeys(self, keys) {
+    if (!keys.length) {
+        return;
+    }
+    const message = unknownKeysMessage(viewLabel(self), keys);
+    console.warn(message);
+    try {
+        getNotificationSink(self).notify(message, 'warning');
+    }
+    catch {
+        // a view built outside a session has nowhere to put it
+    }
+}
+/**
+ * Name the row lists a view refused whole. `withLaunchInput` splits an authored
+ * array into the recipes a launcher resolves and the built snapshots MST
+ * restores, per entry — but a row list is indexed against the view's `levels`
+ * and per-level tracks, so a list holding both kinds has no correct split and
+ * is refused rather than renumbered.
+ */
+export function reportMalformedRows(self, keys) {
+    if (!keys.length) {
+        return;
+    }
+    const message = `${viewLabel(self)} refused ${keys.join(', ')}: the list mixes built view snapshots with recipes to open one, and the rows index against the levels between them. Write all of them one way.`;
+    console.warn(message);
+    try {
+        getNotificationSink(self).notify(message, 'warning');
+    }
+    catch {
+        // a view built outside a session has nowhere to put it
+    }
+}
+/**
+ * What every surface calls v4's nested `init`. v5 takes every setting directly
+ * on the view object and unwraps the nesting on the way in, so the settings
+ * still arrive — this names the spelling to fix while they do.
+ */
+export function legacyInitMessage(label) {
+    return `${label} nests its settings under "init", which is deprecated: write every setting directly on the view object.`;
+}
+/**
+ * Name a snapshot that still writes v4's nested `init`. The console alone,
+ * unlike the two reporters above: the settings were applied, so there is
+ * nothing for a visitor to act on and a warning toast over a working view is
+ * noise. `jbrowse validate` is where the author of the config hears about it.
+ */
+export function reportLegacyInit(self) {
+    console.warn(legacyInitMessage(viewLabel(self)));
+}

package/esm/util/unzip.d.ts

@@ -0,0 +1 @@
+export { unzip } from '@gmod/bgzf-filehandle';

package/esm/util/unzip.js

@@ -0,0 +1,6 @@
+// Deliberately its own entry rather than a name on the util barrel:
+// @gmod/bgzf-filehandle declares no `sideEffects`, so webpack cannot tree-shake
+// a re-export of it out of the barrel, and the barrel has ~1090 importers —
+// including eager plugin entries. Re-exporting `unzip` there put bgzf + pako
+// (~180KB) on the startup path of every page load.
+export { unzip } from '@gmod/bgzf-filehandle';

package/esm/util/useEventCallback.d.ts

@@ -0,0 +1 @@
+export declare function useEventCallback<Args extends unknown[], Return>(fn: (...args: Args) => Return): (...args: Args) => Return;

package/esm/util/useEventCallback.js

@@ -0,0 +1,16 @@
+import { useCallback, useLayoutEffect, useRef } from 'react';
+// Observer-safe replacement for React's useEffectEvent. Returns a stable
+// callback that always invokes the latest `fn`.
+//
+// React's useEffectEvent reads stale state inside mobx-react `observer()`
+// components (its impl swap does not take effect under observer's reactive
+// render), and nearly every JBrowse component is an observer. Here the ref is
+// updated in a layout effect — which runs before paint and before any browser
+// event can fire the stable callback, so it never reads a stale closure.
+export function useEventCallback(fn) {
+    const ref = useRef(fn);
+    useLayoutEffect(() => {
+        ref.current = fn;
+    });
+    return useCallback((...args) => ref.current(...args), []);
+}

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];
 }