@jbrowse/core 4.3.0 → 5.0.0-beta.2

package/esm/util/rowStackGeometry.js

@@ -0,0 +1,70 @@
+/**
+ * Mouse-Y → row index for the displays that stack rows behind
+ * `useRowVirtualScroll`.
+ *
+ * That hook is what makes the arithmetic subtle, so the reader lives beside it.
+ * `applyRowResizeWheel` sets `scrollTop` to `rowUnderMouse * newRowHeight -
+ * mouseY` to pin the row under the cursor, which leaves it fractional, and it
+ * lets `rowHeight` fall to `viewportHeight / nrow` — sub-pixel on a
+ * cohort-sized track. Two rules follow, and each caller used to restate them:
+ *
+ * - **Ask at the pixel's centre.** Rasterization fills a pixel when its centre
+ *   falls inside the rect, so the centre is the scanline the colour the reader
+ *   is pointing at was decided on. The top edge misses by `0.5 / rowHeight`
+ *   rows — 5.4 of them on a 2,504-sample matrix at the default fit height.
+ * - **Floor `mouseY` before adding `scrollTop`.** The canvas draws at
+ *   `row * rowHeight - scrollTop` with `scrollTop` unrounded; flooring the sum
+ *   snaps to a pixel grid the content is not on. This is the half a reader gets
+ *   backwards.
+ */
+/** Content-space Y of the centre of the screen pixel `mouseY` is in. */
+export function contentYAt(mouseY, stack) {
+    const { scrollTop = 0, topOffset = 0 } = stack;
+    return Math.floor(mouseY) + 0.5 + scrollTop - topOffset;
+}
+/** Continuous row coordinate at `mouseY`; callers round to suit. */
+export function rowCoordAt(mouseY, stack) {
+    return contentYAt(mouseY, stack) / stack.rowHeight;
+}
+/** The row `mouseY` is on. Negative above the rows area, and not range-checked. */
+export function rowIndexAt(mouseY, stack) {
+    return Math.floor(rowCoordAt(mouseY, stack));
+}
+/**
+ * Half-open `[startRow, endRow)` covered by a vertical px span, ready to
+ * `slice` a sample list with.
+ *
+ * Both ends are the row at that pixel's centre and the range includes both, so
+ * a span can never come back empty: a drag straight across one row — which
+ * `useDragSelection` supports, gating on X alone — covers the row it is on.
+ * Taking `endRow` as the `ceil` of the same coordinate instead collapsed on
+ * every exact row boundary, one pixel row in every `rowHeight`.
+ */
+export function rowSpanAt(y0, y1, stack) {
+    const first = rowIndexAt(Math.min(y0, y1), stack);
+    const last = rowIndexAt(Math.max(y0, y1), stack);
+    return { startRow: Math.max(0, first), endRow: Math.max(0, last + 1) };
+}
+/**
+ * The rows whose *drawn* cell covers `mouseY`, nearest first.
+ *
+ * Row r occupies `[r*rowHeight, r*rowHeight + drawnRowHeight)`.
+ * `drawnRowHeight` is the height the painter *resolved* for this `rowHeight`,
+ * not the floor it clamps to — pass `drawnCellHeightPx(rowHeight)` from the
+ * module generated out of the display's own shader (ADR-051), so what is
+ * painted and what is pickable stay one rule. At `rowHeight` above the floor it
+ * equals `rowHeight`, the band collapses to `nearest`, and only sub-pixel rows
+ * stack several under one drawn pixel — where the last drawn wins, and
+ * `nearest` is it.
+ *
+ * Walking down to `lowest` keeps those rows hoverable when the nearest one has
+ * nothing to report.
+ */
+export function rowsUnderPointer(mouseY, stack, drawnRowHeight) {
+    const y = contentYAt(mouseY, stack);
+    const { rowHeight } = stack;
+    return {
+        nearest: Math.floor(y / rowHeight),
+        lowest: Math.max(0, Math.floor((y - drawnRowHeight) / rowHeight) + 1),
+    };
+}

package/esm/util/rpc.d.ts

@@ -1,2 +1,17 @@
-import type { RpcResult } from './librpc.ts';
+import type { RpcResult } from '../rpc/RpcServer.ts';
+/**
+ * Type guard to check if a value is an RpcResult.
+ * Used to detect when a renderer has returned pre-serialized data with transferables.
+ *
+ * Note: Transferables flow only from worker to main thread (in responses),
+ * not from main thread to worker. This is because the render results contain
+ * ImageBitmaps and ArrayBuffers that benefit from zero-copy transfer.
+ */
 export declare function isRpcResult(value: unknown): value is RpcResult;
+/**
+ * Take the `rpcResult` envelope off if there is one. Distributes over a union,
+ * because a method can wrap one arm and not another — only the data half of the
+ * canvas gates owns buffers worth transferring.
+ */
+export type UnwrapRpcResult<T> = T extends RpcResult<infer V> ? V : T;
+export declare function unwrapRpcResult<T>(value: T): UnwrapRpcResult<T>;

package/esm/util/rpc.js

@@ -1,6 +1,17 @@
+/**
+ * Type guard to check if a value is an RpcResult.
+ * Used to detect when a renderer has returned pre-serialized data with transferables.
+ *
+ * Note: Transferables flow only from worker to main thread (in responses),
+ * not from main thread to worker. This is because the render results contain
+ * ImageBitmaps and ArrayBuffers that benefit from zero-copy transfer.
+ */
 export function isRpcResult(value) {
     return (typeof value === 'object' &&
         value !== null &&
         '__rpcResult' in value &&
-        value.__rpcResult);
+        value.__rpcResult === true);
+}
+export function unwrapRpcResult(value) {
+    return (isRpcResult(value) ? value.value : value);
 }

package/esm/util/rxjs.d.ts

@@ -1,4 +1,33 @@
 import { Observable } from 'rxjs';
 import type { StopToken } from './stopToken.ts';
 import type { Observer } from 'rxjs';
-export declare function ObservableCreate<T>(func: (arg: Observer<T>) => void | Promise<void>, _stopToken?: StopToken): Observable<T>;
+/**
+ * Wrapper for rxjs Observable.create with improved error handling and aborting
+ * support.
+ *
+ * A `stopToken` errors the subscriber with an abort error the moment the token
+ * is stopped, rather than waiting for `func` to finish work whose result is
+ * already discarded. The fetch paths filter abort errors out (`isAbortException`)
+ * so a cancel does not surface as a track error. It cannot interrupt `func`
+ * itself — a body doing long synchronous work still needs its own
+ * `checkStopToken` ticks — but it does stop delivery downstream.
+ *
+ * @param func - observer function, could be async
+ */
+export declare function ObservableCreate<T>(func: (arg: Observer<T>) => void | Promise<void>, stopToken?: StopToken): Observable<T>;
+/**
+ * Subscribe to an observable and resolve when it completes, running `onNext` per
+ * item as it arrives — the streaming shape for parsing items out of a feature
+ * stream rather than collecting them first.
+ *
+ * **`onNext` throwing rejects the promise.** rxjs does not do that on its own:
+ * an exception out of a `next` handler goes to its global unhandled-error hook,
+ * so the subscriber keeps being fed and `complete` still fires — a bare promise
+ * around that resolves as *success* with the items silently missing. Beside
+ * `ObservableCreate` because it is the other half of the pattern: the adapter
+ * wraps its body in that, the RPC `await`s this, so a per-item parse failure
+ * surfaces as a track error instead of a blank-but-loaded track.
+ *
+ * The source is unsubscribed on the first throw.
+ */
+export declare function subscribeToObservable<T>(observable: Observable<T>, onNext: (item: T) => void): Promise<void>;

package/esm/util/rxjs.js

@@ -1,16 +1,94 @@
 import { Observable } from 'rxjs';
-export function ObservableCreate(func, _stopToken) {
+import { stopTokenSignal } from './stopToken.js';
+/**
+ * Wrapper for rxjs Observable.create with improved error handling and aborting
+ * support.
+ *
+ * A `stopToken` errors the subscriber with an abort error the moment the token
+ * is stopped, rather than waiting for `func` to finish work whose result is
+ * already discarded. The fetch paths filter abort errors out (`isAbortException`)
+ * so a cancel does not surface as a track error. It cannot interrupt `func`
+ * itself — a body doing long synchronous work still needs its own
+ * `checkStopToken` ticks — but it does stop delivery downstream.
+ *
+ * @param func - observer function, could be async
+ */
+export function ObservableCreate(func, stopToken) {
     return new Observable((observer) => {
-        try {
-            const ret = func(observer);
-            if (ret?.catch) {
-                ret.catch((error) => {
-                    observer.error(error);
-                });
-            }
+        const { signal, dispose } = stopTokenSignal(stopToken);
+        const stop = () => {
+            observer.error(signal.reason);
+        };
+        if (signal.aborted) {
+            // stopped before subscribe: no 'abort' event is coming
+            stop();
         }
-        catch (error) {
-            observer.error(error);
+        else {
+            signal.addEventListener('abort', stop);
+            try {
+                const ret = func(observer);
+                if (ret?.catch) {
+                    ret.catch((error) => {
+                        observer.error(error);
+                    });
+                }
+            }
+            catch (error) {
+                observer.error(error);
+            }
         }
+        return () => {
+            signal.removeEventListener('abort', stop);
+            dispose();
+        };
+    });
+}
+/**
+ * Subscribe to an observable and resolve when it completes, running `onNext` per
+ * item as it arrives — the streaming shape for parsing items out of a feature
+ * stream rather than collecting them first.
+ *
+ * **`onNext` throwing rejects the promise.** rxjs does not do that on its own:
+ * an exception out of a `next` handler goes to its global unhandled-error hook,
+ * so the subscriber keeps being fed and `complete` still fires — a bare promise
+ * around that resolves as *success* with the items silently missing. Beside
+ * `ObservableCreate` because it is the other half of the pattern: the adapter
+ * wraps its body in that, the RPC `await`s this, so a per-item parse failure
+ * surfaces as a track error instead of a blank-but-loaded track.
+ *
+ * The source is unsubscribed on the first throw.
+ */
+export function subscribeToObservable(observable, onNext) {
+    return new Promise((resolve, reject) => {
+        // A box rather than two bare `let`s: oxlint narrows a flag assigned only
+        // inside a closure to its initializer and reports the reads as always-false.
+        // `subscription` is genuinely still undefined during a synchronous source's
+        // first emissions, which is why it is read optionally below.
+        const state = {
+            failed: false,
+        };
+        state.subscription = observable.subscribe({
+            next: item => {
+                if (!state.failed) {
+                    try {
+                        onNext(item);
+                    }
+                    catch (e) {
+                        state.failed = true;
+                        // A parser throws an Error in every real case here; the wrap is for
+                        // the rule that a rejection reason must be one, and keeps whatever
+                        // was actually thrown as the `cause`.
+                        reject(e instanceof Error ? e : new Error(String(e), { cause: e }));
+                        state.subscription?.unsubscribe();
+                    }
+                }
+            },
+            error: reject,
+            complete: () => {
+                if (!state.failed) {
+                    resolve();
+                }
+            },
+        });
     });
 }

package/esm/util/sameStrings.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Element-wise equality for two string lists, so a setter can skip rewriting
+ * observable state with contents it already holds.
+ *
+ * A primitive prop gets this for free — MobX drops a write of the same number or
+ * string — and an array does not: a fresh array is a fresh identity, so every
+ * write invalidates everything computed from it however little changed. That
+ * makes an unguarded array setter on a per-mousemove path a re-render per raw
+ * pointer event, which is how both display families came to want this: the
+ * pileup rewriting a chain's read ids while the cursor tracks along one chain,
+ * and the canvas display rewriting its tooltip rows while the cursor sits still
+ * over one feature.
+ */
+export declare function sameStrings(a: readonly string[], b: readonly string[]): boolean;
+/** The same, for a pair that may be absent — two absent lists are equal. */
+export declare function sameOptionalStrings(a: readonly string[] | undefined, b: readonly string[] | undefined): boolean;

package/esm/util/sameStrings.js

@@ -0,0 +1,20 @@
+/**
+ * Element-wise equality for two string lists, so a setter can skip rewriting
+ * observable state with contents it already holds.
+ *
+ * A primitive prop gets this for free — MobX drops a write of the same number or
+ * string — and an array does not: a fresh array is a fresh identity, so every
+ * write invalidates everything computed from it however little changed. That
+ * makes an unguarded array setter on a per-mousemove path a re-render per raw
+ * pointer event, which is how both display families came to want this: the
+ * pileup rewriting a chain's read ids while the cursor tracks along one chain,
+ * and the canvas display rewriting its tooltip rows while the cursor sits still
+ * over one feature.
+ */
+export function sameStrings(a, b) {
+    return a.length === b.length && a.every((s, i) => s === b[i]);
+}
+/** The same, for a pair that may be absent — two absent lists are equal. */
+export function sameOptionalStrings(a, b) {
+    return a === undefined || b === undefined ? a === b : sameStrings(a, b);
+}

package/esm/util/scrollLatch.d.ts

@@ -0,0 +1,4 @@
+export declare function createScrollLatch(timeoutMs?: number): {
+    scroll(e: WheelEvent, cur: number, delta: number, max: number, min?: number): number | null;
+    reset(): void;
+};

package/esm/util/scrollLatch.js

@@ -0,0 +1,59 @@
+// Native browsers latch a wheel gesture to the inner scroller: once an inner
+// panel starts consuming scroll, continued momentum stays in that panel even
+// after it reaches its boundary, and only after the gesture pauses does scroll
+// chain to the outer page. Raw wheel bubbling lacks this — the event spills to
+// the page the instant the panel hits its limit, so a single continuous gesture
+// scrolls the page unexpectedly. createScrollLatch reproduces the native
+// behavior in one place so every wheel handler gets it identically.
+// gap between wheel events long enough to count as a new gesture; continuous
+// trackpad/mouse scrolling fires every ~16ms, so 200ms reliably marks a pause
+const LATCH_TIMEOUT_MS = 200;
+export function createScrollLatch(timeoutMs = LATCH_TIMEOUT_MS) {
+    // timestamp of the previous wheel event (any event, not just ones that
+    // moved the panel) and whether the current gesture has latched onto this
+    // panel by actually scrolling it. A gap > timeoutMs between events marks a
+    // pause, i.e. the start of a new gesture.
+    let lastEvent = -Infinity;
+    let latched = false;
+    return {
+        // Apply one wheel event to a vertical panel with native-style latching.
+        // Given the current scroll offset, the delta (already normalized to
+        // pixels), and the scrollable max (min defaults to 0), returns the clamped
+        // new offset when the panel moves, or null when it stays put. preventDefault
+        // fires both when the panel scrolls AND when it sits at a boundary mid-
+        // gesture, so the page only takes over after the gesture pauses. The whole
+        // boundary/latch/preventDefault contract lives here so no caller can derive
+        // it incorrectly — they just apply the returned offset.
+        //
+        // Latching keys off gesture continuity, not panel movement: once a
+        // continuous gesture has scrolled the panel it stays latched — suppressing
+        // page scroll — through any amount of continued over-scroll at the
+        // boundary, and only releases after the wheel events actually pause. A
+        // gesture that *starts* at the boundary never latches, so it chains to the
+        // page immediately (native behavior).
+        scroll(e, cur, delta, max, min = 0) {
+            if (e.timeStamp - lastEvent >= timeoutMs) {
+                latched = false;
+            }
+            lastEvent = e.timeStamp;
+            const next = Math.max(min, Math.min(max, cur + delta));
+            if (next !== cur) {
+                latched = true;
+                e.preventDefault();
+                return next;
+            }
+            if (latched) {
+                e.preventDefault();
+            }
+            return null;
+        },
+        // Forget the gesture state so the next event is treated as a fresh gesture.
+        // Called when the pointer leaves the panel: a gesture the browser has
+        // latched to this element must not keep the page suppressed once the cursor
+        // is elsewhere.
+        reset() {
+            lastEvent = -Infinity;
+            latched = false;
+        },
+    };
+}

package/esm/util/selectNamedRegions.d.ts

@@ -0,0 +1,136 @@
+import type { Region } from './types/data.ts';
+/**
+ * Resolve caller-supplied region names against an assembly's own regions,
+ * preserving the requested order and dropping names that match nothing.
+ *
+ * An entry containing `*` is a glob matched against the refName, which is what
+ * makes a fragmented assembly tractable: a haplotype-resolved genome wants "all
+ * of hap1" (`*_hap1`), not a hand-maintained list of its 16 scaffolds that goes
+ * stale the moment the assembly is rebuilt. A glob contributes its matches in
+ * the ASSEMBLY's order (the only order it can mean); exact names contribute in
+ * the CALLER's order, so an explicit list still controls layout. Duplicates
+ * across entries are dropped, so `['chr1_hap1', '*_hap1']` is chr1 first then
+ * the rest.
+ *
+ * AN EXACT REFNAME BEATS THE GLOB READING, which is the only reason `*` is safe
+ * to hand a user as a syntax: `*` is a legal character in a real contig name and
+ * the names carrying it are the ones nobody would think to escape. GRCh38's ALT
+ * decoys are HLA allele names — `HLA-A*01:01:01:01` — so a pattern typed to name
+ * one allele was compiled to `^HLA-A.*01:01:01:01$`, which matches that contig
+ * (hence it looked fine) and every other HLA-A allele with the same last four
+ * fields. Trying the literal lookup first costs one Map hit and means a name
+ * that IS a contig always resolves to that contig; only a name matching nothing
+ * is reinterpreted as a pattern.
+ *
+ * Selecting from the assembly's own region objects (rather than synthesizing
+ * them) keeps coordinates and lengths correct.
+ *
+ * THERE IS DELIBERATELY NO CEILING on how many regions a glob may resolve to.
+ * `["*"]` on a scaffold-level assembly really does mean every contig, which is
+ * no more than `showAllRegionsInAssembly` already hands to `setDisplayedRegions`.
+ * A cap here could only truncate — silently returning some of what was asked
+ * for, which is the failure mode this file keeps being fixed for. The search
+ * box's picker does bound its bulk-select row, and that is a different thing: it
+ * withholds an OFFER, leaving every match still pickable one at a time, rather
+ * than quietly resolving a list to a prefix of itself.
+ *
+ * BOTH READINGS GO THROUGH THE ASSEMBLY'S ALIASES, and they have to, because
+ * only one of them used to. An exact name has always resolved via
+ * `getCanonicalRefName`, so `['chr1']` picks out a contig an Ensembl-named
+ * assembly calls `1` — but the glob was tested against `region.refName`, the
+ * canonical name alone, so `['chr*']` on that same assembly matched nothing at
+ * all. The literal working where the pattern silently fails is the worst
+ * possible split: the caller has no way to tell "this assembly has no such
+ * contigs" from "globs don't see the names you're using". Pass `allRefNames`
+ * (canonical names AND aliases — `buildRefNameMaps` identity-maps every region,
+ * so it is a strict superset) and a pattern sees what a literal sees.
+ *
+ * It is optional ONLY because this is published ABI and the three-argument form
+ * predates it; an external plugin still calling that gets the canonical-only
+ * matching it always got. It is not optional because there is a state where an
+ * assembly has regions but not yet names — `setLoaded` writes `volatileRegions`
+ * and `refNameAliases` in one action, so no such state exists, and every
+ * in-tree caller (all of them through `resolveNamedRegions`) passes both.
+ */
+export declare function selectNamedRegions(regions: readonly Region[], names: readonly string[], getCanonicalRefName: (name: string) => string | undefined, allRefNames?: readonly string[]): Region[];
+/**
+ * Split a user-typed or URL-supplied region list into the entries
+ * `selectNamedRegions` takes. Comma-separated, because the two things anyone
+ * writes here are one glob (`*_MATERNAL`) or a short explicit list
+ * (`chr1, chr2`), and neither wants punctuation ceremony. Only the comma
+ * splits, so an HLA allele name — which carries both `*` and `:` — survives
+ * intact.
+ *
+ * Whitespace-trimmed and empties dropped, so a trailing comma, a box holding
+ * only spaces, and a bare `&regions=` all mean the same thing as nothing at
+ * all: no restriction, whole assembly. That last one is why this lives in core
+ * beside the matcher rather than next to the text box that first needed it —
+ * `&regions=` was reading the same syntax through a bare `split(',')`, so
+ * `&regions=chr1,%20chr2` dropped chr2 on the floor without a word and
+ * `&regions=` warned that a list of one empty name had matched nothing.
+ */
+export declare function parseRegionNames(value: string): string[];
+/**
+ * `selectNamedRegions` plus the report a miss owes the user, which each of the
+ * four views taking `displayedRegionNames` had written out for itself — and two
+ * of them had not written at all, so a typo there showed the whole assembly and
+ * read as the field being ignored. A typo is no longer only a hand-authored-JSON
+ * mistake either: the dotplot and synteny import forms put this syntax in a text
+ * box.
+ *
+ * `undefined` means "this list picks out nothing" — the caller's cue to apply
+ * its own fallback, which is the part that genuinely differs between them: the
+ * LGV keeps a defaultSession's existing navigation, the circular view and a
+ * synteny row draw the whole assembly, and a dotplot axis is left as the
+ * regions autorun populated it.
+ */
+export declare function resolveNamedRegions({ regions, names, assemblyName, getCanonicalRefName, allRefNames, notify, }: {
+    regions: readonly Region[];
+    names: readonly string[];
+    assemblyName: string;
+    getCanonicalRefName: (name: string) => string | undefined;
+    allRefNames?: readonly string[];
+    notify: (message: string) => void;
+}): Region[] | undefined;
+export interface RefNameMatchSource {
+    regions?: readonly {
+        refName: string;
+    }[];
+    allRefNames?: readonly string[];
+    getCanonicalRefName: (name: string) => string | undefined;
+}
+/**
+ * How many regions an INTERACTIVE glob will open at once. Displaying a few
+ * hundred whole chromosomes is ordinary — GRCh38 with its alts and decoys is
+ * ~640 refNames, and showAllRegionsInAssembly lays out every one — so this sits
+ * well above any real chromosome set and well below a scaffold-level assembly's
+ * contig count. Past it the offer is WITHHELD, never truncated: a bulk action
+ * reading "all of them" that opens the first thousand is the one behaviour not
+ * worth having.
+ *
+ * `selectNamedRegions` itself is deliberately unbounded — see its docstring.
+ * The bound belongs to the surfaces a person types at, not to the resolver a
+ * session spec goes through, because only the former has a way to say "too
+ * many, narrow it" and only the latter is a written-down intention.
+ */
+export declare const MAX_GLOB_REGIONS = 1000;
+/**
+ * The canonical refNames a search-box query picks out, in ASSEMBLY order.
+ *
+ * Shared by the dropdown's option list and by what Enter does, which is the
+ * whole point of it being one function: those two answer for the same typed
+ * text, and a surface-by-surface reading of one syntax is the split this file
+ * keeps being fixed for. A substring match (what the box has always done) and,
+ * when the text contains `*`, an anchored glob — union, never one instead of
+ * the other, since `*` is a legal refName character and a literal hit must
+ * survive the pattern reading of the same text.
+ *
+ * Matching runs over every name the assembly answers to, aliases included, and
+ * resolves hits to the canonical name — the name the view will display, and the
+ * same choice `searchRefNames` makes. Emitting by walking `regions` is what
+ * keeps assembly order rather than alias-file order.
+ *
+ * Bounded: matching stops one hit past `ceiling`, so a caller can tell "at the
+ * limit" from "under it" without the scan being unbounded.
+ */
+export declare function matchRefNames(assembly: RefNameMatchSource | undefined, inputValue: string, ceiling: number): string[];