@jbrowse/core 4.3.0 → 5.0.0-beta.2

package/esm/util/getFileName.js

@@ -0,0 +1,34 @@
+// Handles both forward slashes and Windows backslashes in file:// URLs
+function filenameFromPath(path) {
+    return path.replaceAll('\\', '/').split('/').at(-1) ?? '';
+}
+// A query string is a request parameter, not part of the name: a presigned S3 or
+// GCS link ends in a few hundred characters of `?X-Amz-Signature=...`, and every
+// caller here either shows the name to someone or matches an extension against
+// the end of it. Stripped for a URI only — `?` is a legal character in a POSIX
+// filename, so a local path keeps whatever it was given.
+function withoutQuery(filename) {
+    return filename.split(/[?#]/)[0];
+}
+/**
+ * The bare filename a location refers to, for every location type — a Blob and
+ * a FileHandle carry their name directly, a URI and a local path carry it as the
+ * last path segment.
+ *
+ * Its own module rather than living in `tracks.ts` because the assembly form
+ * helpers need it too, and `tracks.ts` pulls in MST and the configuration
+ * system. Re-exported from `tracks.ts`, which is the import path plugins use.
+ */
+export function getFileName(location) {
+    switch (location.locationType) {
+        case 'BlobLocation':
+        case 'FileHandleLocation':
+            return location.name;
+        case 'UriLocation':
+            return withoutQuery(filenameFromPath(location.uri));
+        case 'LocalPathLocation':
+            return filenameFromPath(location.localPath);
+        default:
+            return '';
+    }
+}

package/esm/util/getLocationUri.d.ts

@@ -0,0 +1,49 @@
+import type { FileLocation } from './types/data.ts';
+/**
+ * A `UriLocation` as the absolute address it actually fetches — its `uri`
+ * resolved against `baseUri`, so a config's relative path reads as the URL the
+ * network saw rather than the fragment the config held.
+ */
+export declare function resolveUri({ uri, baseUri, }: {
+    uri: string;
+    baseUri?: string;
+}): string;
+/**
+ * An address with its query string dropped, which is what makes it safe to put
+ * on screen. A presigned S3 or GCS link carries its credential in the query — a
+ * few hundred characters of `?X-Amz-Signature=…` — and a notice that renders one
+ * puts it in front of whoever is looking at the screen and into every screenshot
+ * of it. The host and path are the whole diagnostic anyway.
+ *
+ * Same reasoning as {@link getFileName}'s own strip. A URL only: `?` is a legal
+ * character in a POSIX filename, so a path keeps whatever it was given, and a
+ * scheme is what tells the two apart when the caller has a bare string rather
+ * than a typed location.
+ */
+export declare function redactSource(source: string): string;
+/**
+ * Where a location's bytes come from, as an address worth showing someone, or
+ * undefined when it has none.
+ *
+ * "None" is the honest answer for a Blob and a FileHandle: they are bytes the
+ * user handed the page, with no address to go and check. It is the answer a
+ * stalled-load notice needs — the notice exists to name a server that stopped
+ * answering, and there is no server behind either of those.
+ */
+export declare function getLocationUri(location: FileLocation): string | undefined;
+/**
+ * A download phase that names the file it is fetching, for the stalled-load
+ * notice — a source-carrying phase when the location has an address to show, and
+ * the bare label when it does not, which is the same thing the phase helpers
+ * always took.
+ *
+ * **Only for a read this process does not perform.** Anything going through
+ * `fetchAndMaybeUnzip` takes its source off the filehandle and needs none of
+ * this; what is left is the readers that open a handle and then do their own
+ * reads through it — `@gmod/twobit` and `@gmod/indexedfasta` — where the phase
+ * has to be built from the config the handle was opened from instead.
+ */
+export declare function downloadPhase(message: string, location: FileLocation): string | {
+    message: string;
+    source: string;
+};

package/esm/util/getLocationUri.js

@@ -0,0 +1,63 @@
+import { isLocalPathLocation, isUriLocation } from './types/data.js';
+/**
+ * A `UriLocation` as the absolute address it actually fetches — its `uri`
+ * resolved against `baseUri`, so a config's relative path reads as the URL the
+ * network saw rather than the fragment the config held.
+ */
+export function resolveUri({ uri, baseUri = '', }) {
+    try {
+        return new URL(uri, baseUri).href;
+    }
+    catch {
+        return uri;
+    }
+}
+/**
+ * An address with its query string dropped, which is what makes it safe to put
+ * on screen. A presigned S3 or GCS link carries its credential in the query — a
+ * few hundred characters of `?X-Amz-Signature=…` — and a notice that renders one
+ * puts it in front of whoever is looking at the screen and into every screenshot
+ * of it. The host and path are the whole diagnostic anyway.
+ *
+ * Same reasoning as {@link getFileName}'s own strip. A URL only: `?` is a legal
+ * character in a POSIX filename, so a path keeps whatever it was given, and a
+ * scheme is what tells the two apart when the caller has a bare string rather
+ * than a typed location.
+ */
+export function redactSource(source) {
+    return source.includes('://') ? source.split(/[?#]/)[0] : source;
+}
+/**
+ * Where a location's bytes come from, as an address worth showing someone, or
+ * undefined when it has none.
+ *
+ * "None" is the honest answer for a Blob and a FileHandle: they are bytes the
+ * user handed the page, with no address to go and check. It is the answer a
+ * stalled-load notice needs — the notice exists to name a server that stopped
+ * answering, and there is no server behind either of those.
+ */
+export function getLocationUri(location) {
+    if (isUriLocation(location)) {
+        return redactSource(resolveUri(location));
+    }
+    if (isLocalPathLocation(location)) {
+        return location.localPath;
+    }
+    return undefined;
+}
+/**
+ * A download phase that names the file it is fetching, for the stalled-load
+ * notice — a source-carrying phase when the location has an address to show, and
+ * the bare label when it does not, which is the same thing the phase helpers
+ * always took.
+ *
+ * **Only for a read this process does not perform.** Anything going through
+ * `fetchAndMaybeUnzip` takes its source off the filehandle and needs none of
+ * this; what is left is the readers that open a handle and then do their own
+ * reads through it — `@gmod/twobit` and `@gmod/indexedfasta` — where the phase
+ * has to be built from the config the handle was opened from instead.
+ */
+export function downloadPhase(message, location) {
+    const source = getLocationUri(location);
+    return source === undefined ? message : { message, source };
+}

package/esm/util/getRelativeX.d.ts

@@ -0,0 +1,4 @@
+export declare function getRelativeX(event: {
+    clientX: number;
+    target: EventTarget | null;
+}, element: HTMLElement | null): number;

package/esm/util/getRelativeX.js

@@ -0,0 +1,7 @@
+// Against an element handed in, deliberately: a rubberband drag tracks the
+// pointer across the whole document, so the box it projects through is the one
+// it started in and not whatever the cursor is now over. For the ordinary case —
+// a handler measuring against its own element — see `eventPoint`.
+export function getRelativeX(event, element) {
+    return event.clientX - (element?.getBoundingClientRect().left ?? 0);
+}

package/esm/util/getStr.d.ts

@@ -0,0 +1,6 @@
+/**
+ * A value rendered as a display string: a UriLocation as its resolved href, any
+ * other object as JSON, everything else via String(). Shared by the DataGrid
+ * column-width heuristic and the feature-detail panels.
+ */
+export declare function getStr(obj: unknown): string;

package/esm/util/getStr.js

@@ -0,0 +1,15 @@
+import { resolveUri } from './getLocationUri.js';
+import { isObject } from './objectUtils.js';
+import { isUriLocation } from './types/data.js';
+/**
+ * A value rendered as a display string: a UriLocation as its resolved href, any
+ * other object as JSON, everything else via String(). Shared by the DataGrid
+ * column-width heuristic and the feature-detail panels.
+ */
+export function getStr(obj) {
+    return isObject(obj)
+        ? isUriLocation(obj)
+            ? resolveUri(obj)
+            : JSON.stringify(obj)
+        : String(obj);
+}

package/esm/util/highlights.d.ts

@@ -0,0 +1,21 @@
+import type { IAnyStateTreeNode } from '@jbrowse/mobx-state-tree';
+import type { Theme } from '@mui/material';
+export interface HighlightType {
+    start: number;
+    end: number;
+    assemblyName?: string;
+    refName: string;
+    color?: string;
+    label?: string;
+}
+export declare function revealHighlightsOnGrowth(node: IAnyStateTreeNode, count: () => number): void;
+export declare function highlightKey(h: {
+    assemblyName?: string;
+    refName: string;
+    start: number;
+    end: number;
+}, i: number): string;
+export declare function getHighlightColor(highlight: {
+    color?: string;
+}, theme: Theme, alpha?: number): import("./colord.ts").Colord;
+export declare function coerceHighlight(h: string | HighlightType, defaultAssembly: string, isValidRefName: (refName: string, assemblyName?: string) => boolean): HighlightType | undefined;

package/esm/util/highlights.js

@@ -0,0 +1,100 @@
+import { addDisposer } from '@jbrowse/mobx-state-tree';
+import { autorun } from 'mobx';
+import { colord } from './colord.js';
+import { parseLocString } from './locString.js';
+import { getSession } from './mstUtils.js';
+// Bands and bookmark overlays both render only while the session-wide
+// `highlightsVisible` flag is on, so anything added while it is off draws
+// nothing at all, which reads as "it didn't work". Watching the collection
+// grow reveals for every path that adds to it rather than asking each call
+// site to remember. `count` is seeded before the autorun so restoring a
+// session that deliberately persisted bands-off doesn't flip it back on, and
+// removals only lower the baseline — they never re-reveal, or the toggle could
+// never be turned off.
+export function revealHighlightsOnGrowth(node, count) {
+    let prevCount = count();
+    addDisposer(node, autorun(function highlightRevealAutorun() {
+        const newCount = count();
+        if (newCount > prevCount) {
+            getSession(node).revealHighlights();
+        }
+        prevCount = newCount;
+    }));
+}
+// Highlight regions have no id and can duplicate, so the trailing index only
+// breaks ties between otherwise-identical regions. Wrapping the array index in
+// this helper also keeps it out of the `no-array-index-key` lint's view.
+// JSON-encoding the fields (rather than joining on a delimiter) avoids
+// collisions when a refName contains the delimiter, e.g. `chr1_2`@3 vs
+// `chr1`@`2_3`.
+export function highlightKey(h, i) {
+    return JSON.stringify([h.assemblyName, h.refName, h.start, h.end, i]);
+}
+// User-supplied color is used as-is so explicit alpha is preserved; otherwise
+// fall back to the theme highlight color at the given alpha. Shared by the LGV
+// and dotplot highlight bands (which differ only in their default alpha).
+export function getHighlightColor(highlight, theme, alpha = 0.2) {
+    return highlight.color
+        ? colord(highlight.color)
+        : colord(theme.palette.highlight.main).alpha(alpha);
+}
+function tryParseJson(s) {
+    try {
+        const v = JSON.parse(s);
+        return v && typeof v === 'object'
+            ? v
+            : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+// a string is either a loc string ("chr1:100-200") or a JSON-encoded
+// HighlightType (the URL wire-format, since URL params can't carry objects).
+// note: the jbrowse-web &highlight= URL param is space-split, so the JSON-string
+// form only survives when it contains no spaces; a label with a space is
+// shattered by the split — pass a HighlightType object instead
+function parseJsonHighlight(s, defaultAssembly) {
+    const json = s.trimStart().startsWith('{') ? tryParseJson(s) : undefined;
+    return json &&
+        typeof json.refName === 'string' &&
+        typeof json.start === 'number' &&
+        typeof json.end === 'number'
+        ? {
+            refName: json.refName,
+            start: json.start,
+            end: json.end,
+            assemblyName: typeof json.assemblyName === 'string'
+                ? json.assemblyName
+                : defaultAssembly,
+            color: typeof json.color === 'string' ? json.color : undefined,
+            label: typeof json.label === 'string' ? json.label : undefined,
+        }
+        : undefined;
+}
+// The `{assembly}` prefix a locstring may carry is kept, not overwritten with
+// the default: on a dotplot the two axes are two different assemblies, so
+// `{mm10}chr1:1-100` stamped with the horizontal axis' assembly drew the band on
+// the wrong axis (see DotplotView's axisHighlightRegion, which routes by exactly
+// this field) with nothing said. Single-assembly views are unaffected — their
+// only prefix is the default anyway.
+function parseLocHighlight(s, defaultAssembly, isValidRefName) {
+    const { assemblyName, refName, start, end } = parseLocString(s, isValidRefName);
+    return start !== undefined && end !== undefined
+        ? { refName, start, end, assemblyName: assemblyName ?? defaultAssembly }
+        : undefined;
+}
+// Normalize an `init.highlight` entry (HighlightType object, JSON string, or
+// loc string) into a HighlightType, defaulting the assemblyName. Shared by
+// LinearGenomeView and DotplotView, whose `init.highlight` accept the same
+// three forms — the JSON shape-check in particular has to stay identical or a
+// highlight that works in one view silently drops in the other.
+export function coerceHighlight(h, defaultAssembly, 
+// takes the assembly a `{...}` prefix named, so a caller with more than one
+// assembly in play validates the refName against the one the entry asked for
+isValidRefName) {
+    return typeof h === 'object'
+        ? { ...h, assemblyName: h.assemblyName ?? defaultAssembly }
+        : (parseJsonHighlight(h, defaultAssembly) ??
+            parseLocHighlight(h, defaultAssembly, isValidRefName));
+}

package/esm/util/hooks.d.ts

@@ -0,0 +1,168 @@
+import type { RefObject } from 'react';
+export declare function useFocusOnInteraction(ref: RefObject<HTMLElement | null>, onInteract: () => void): void;
+export declare function useDebounce<T>(value: T, delay: number): T;
+export declare function useWidthSetter(view: {
+    setWidth: (arg: number) => void;
+    id?: string;
+}): RefObject<HTMLDivElement | null>;
+/**
+ * Build a value exactly once per mount — including under React StrictMode,
+ * which `useState(() => build())` does not.
+ *
+ * StrictMode double-invokes a state initializer in development and throws the
+ * SECOND result away. For an ordinary value that is the intended lint: it
+ * surfaces impure initializers and costs nothing. For anything that owns
+ * something — an MST tree, a worker pool, a subscription — it stands up a second
+ * one and then drops the only reference to it, so nothing can ever tear it down,
+ * and it is invisible because the one React kept behaves perfectly.
+ *
+ * A ref is written once and survives the double render; this is React's own
+ * "avoiding recreating the ref contents" pattern.
+ */
+export declare function useCreateOnce<T>(create: () => T): T;
+/**
+ * `useCreateOnce` for an asynchronous factory: returns undefined until
+ * `create` resolves, and rethrows a rejection from render. The value can
+ * resolve after the component is gone — a caller whose value is expensive to
+ * leak should use product-core's `useAsyncEngineLifecycle`, which discards
+ * that late arrival.
+ */
+export declare function useCreateOnceAsync<T>(create: () => Promise<T>): T | undefined;
+/**
+ * Run `cleanup` when the component *really* unmounts.
+ *
+ * "Really" is the whole difficulty, because React does not distinguish a final
+ * unmount from a simulated one. The obvious spelling —
+ * `useEffect(() => () => cleanup(), [])` — is wrong in exactly the environment
+ * most hosts develop in, jbrowse-web included: StrictMode runs
+ * setup → cleanup → setup on a live component, so a cleanup that destroys
+ * something leaves the component holding the destroyed thing for the rest of its
+ * life, with the second setup having nothing to rebuild from. For an MST tree
+ * that is not a quiet degradation — the next read throws `[mobx-state-tree] …
+ * [dead]`.
+ *
+ * So the teardown is deferred by a microtask and cancelled if setup runs again.
+ * StrictMode's cleanup and re-setup are one synchronous block, so the cancel
+ * always wins there; a real unmount never runs setup again, so the microtask
+ * fires.
+ *
+ * This owns a *component's* teardown, not a per-value one: `cleanup` always sees
+ * the latest render's closure, and swapping the thing being torn down mid-life
+ * is not supported. Pair it with {@link useCreateOnce}, which is the shape that
+ * makes that true.
+ *
+ * Deliberately not covered: a subtree hidden with `<Activity>`, which destroys
+ * effects and re-creates them a TASK later rather than synchronously, so the
+ * cancel below cannot reach it. Measured, not assumed — `useFinalUnmount.test.tsx`
+ * pins that hiding tears the value down and showing does not rebuild it, since
+ * `useCreateOnce`'s ref survives the hide. A host that needs a view to survive
+ * being hidden owns the engine itself and keeps it outside the hidden tree.
+ */
+export declare function useFinalUnmount(cleanup: () => void): void;
+/**
+ * `useState` backed by a localStorage key.
+ *
+ * Originally https://usehooks.com/useLocalStorage/, which is per-instance: two
+ * components on the same key each kept their own copy of it, so toggling a
+ * setting in one BreakpointSplitView header left a second one open beside it
+ * showing the old value until it remounted. Instances on a key now subscribe to
+ * each other's writes, and to other tabs' — `subscribeToLocalStorageKey`, which
+ * the grid-bookmark widget shares from its state model.
+ *
+ * The store is read on every notify rather than cached, so nothing here can go
+ * stale against a `localStorage.clear()`. Which also means a functional update
+ * resolves against what is actually stored: two `setValue(v => …)` calls in one
+ * handler used to keep only the second, because both resolved against the value
+ * captured by the render that produced the setter.
+ *
+ * `enabled: false` keeps the value in component state only: nothing is read,
+ * written or shared. Callers use it for a key that isn't meaningful yet (no
+ * assembly chosen, so nothing to scope the key to). A page with no usable store
+ * at all — an RPC worker, SSR, a cross-origin iframe with third-party storage
+ * blocked, which is the embedded products on someone else's page — runs in that
+ * same mode, because reading a key back through a store that dropped the write
+ * answers the default and would report it as the stored value: the control
+ * would revert the instant the user moved it.
+ */
+export declare function useLocalStorage<T>(key: string, initialValue: T, enabled?: boolean): readonly [T, (value: T | ((val: T) => T)) => void];
+/**
+ * The CSS custom property a scroll port publishes its own visible height as, for
+ * descendants that have to size against the surface they actually scroll in.
+ *
+ * `100vh` is the wrong answer for all three of JBrowse's scroll ports and looks
+ * right in the one place it is least wrong: the classic view stack sits under a
+ * 48px AppBar (measured 852 against a 900px window), a workspace panel is an
+ * arbitrary dockview cell, and a bounded embedded view is whatever box the host
+ * gave it. A sticky element's offsets are relative to its scroll port, so a
+ * `max-height` that bounds one has to be too.
+ */
+export declare const SCROLL_PORT_HEIGHT_VAR = "--jbrowse-scrollport-height";
+/**
+ * Publishes {@link SCROLL_PORT_HEIGHT_VAR} on the element the returned ref is
+ * attached to. Put it on the element that actually scrolls; the property
+ * inherits, so anything inside can read it with a `100vh` fallback for hosts
+ * that never mount one.
+ *
+ * Written straight to the node instead of through state on purpose. This sits on
+ * a container wrapping every view, so a re-render per resize frame would
+ * re-render all of them to produce a number only CSS reads.
+ */
+export declare function useScrollPortHeightVar(): RefObject<HTMLDivElement | null>;
+/**
+ * Whether the element the ref is on is taller than the scroll port it sits in —
+ * i.e. whether there is content a user could actually scroll to.
+ *
+ * Not the same question as "does the port overflow": a port can overflow by
+ * trailing space it renders for its own reasons, and a scrollbar offering only
+ * that is worse than none, since it says the page has more to show when it does
+ * not. So this measures the *content* box and leaves the trailing space out of
+ * the comparison, which means the caller has to keep that space outside the
+ * measured element.
+ *
+ * Stable rather than oscillating, and not by luck: turning the answer true adds
+ * a scrollbar, which narrows the content, and narrowing can only make content
+ * taller — so a true answer stays true and a false one stays false.
+ *
+ * `useLayoutEffect`, so the first measurement and the re-render it causes both
+ * land before paint. A view added to the stack scrolls itself into view from a
+ * passive effect, and passive effects run after every layout effect in the tree:
+ * measuring here means the trailing space this gates is already in the DOM by
+ * the time that scroll is computed against it.
+ */
+export declare function useScrollPortOverflow(ref: React.RefObject<HTMLElement | null>): boolean;
+/**
+ * Heights of the chrome boxes a sticky element below them has to clear. Each is
+ * published from a measurement rather than assumed, because the constants they
+ * default to are nominal: `VIEW_HEADER_HEIGHT` and the LGV header bar's height
+ * were written into the CSS by the pin-elements work (#4237) so that the sticky
+ * offsets summing them would be true, and a box pinned to a constant clips its
+ * own content once the root font size grows — measured on the stock theme, the
+ * view header overflows at a 18px root and the LGV controls row at 24px.
+ *
+ * So those CSS heights are minimums and these carry the truth. The fallbacks
+ * keep the nominal answer for the frame before the first measurement, and for a
+ * host that mounts no publisher. A box that stays fixed still publishes — see
+ * the embedded `ViewTitle`, which is a density choice rather than a constraint
+ * now that nothing below it re-derives its height.
+ *
+ * Cheap enough to put on every view: measured across a jbrowse-web session, the
+ * observers behind these fired 0 times over 60 pan frames and 10 zooms, and ~5
+ * times per window resize.
+ */
+export declare const VIEW_HEADER_HEIGHT_VAR = "--jbrowse-view-header-height";
+export declare const LGV_HEADER_HEIGHT_VAR = "--jbrowse-lgv-header-height";
+/**
+ * Publishes the measured height of `ref`'s element as `varName`, set on its
+ * **parent**. The parent, not the element itself: what reads these is a sticky
+ * sibling *below* the measured box, so publishing on the box would put the
+ * property out of the reader's inheritance chain.
+ *
+ * Takes the ref rather than returning one — the boxes being measured are also
+ * the ones a view scrolls into view or hangs a gesture on, so they tend to
+ * already have one.
+ *
+ * Written straight to the node rather than through state, for the reason
+ * {@link useScrollPortHeightVar} gives — and here with the extra one that a
+ * header re-rendering on its own resize is a loop waiting for a rounding error.
+ */
+export declare function useChromeHeightVar(ref: React.RefObject<HTMLElement | null>, varName: string): void;