@jbrowse/core 4.3.0 → 5.0.0-beta.10

package/esm/util/reorder.js

@@ -0,0 +1,83 @@
+/**
+ * Move `idx` within the subsequence of `arr` that `inScope` selects, leaving
+ * every out-of-scope element where it sits.
+ *
+ * The scoped move: one list holds everything, but a move is only ever relative
+ * to a subset of it. "Move this view up" in a tabbed workspace means up past the
+ * previous view IN THIS PANEL, not past whatever happens to precede it in
+ * `session.views` — which may be in another panel entirely and would make the
+ * move look like a no-op.
+ *
+ * Implemented as a permutation of the in-scope positions: pull out the in-scope
+ * elements, reorder that list, then write it back into the same index slots.
+ * That is what keeps out-of-scope elements pinned, and what makes an unscoped
+ * move (everything in scope) exactly `reorder`.
+ */
+export function reorderWithin(arr, idx, direction, inScope) {
+    const slots = [];
+    const scoped = [];
+    for (const [i, item] of arr.entries()) {
+        if (inScope(item, i)) {
+            slots.push(i);
+            scoped.push(item);
+        }
+    }
+    const scopedIdx = slots.indexOf(idx);
+    if (scopedIdx === -1) {
+        return [...arr];
+    }
+    const moved = reorder(scoped, scopedIdx, direction);
+    const next = [...arr];
+    for (const [i, slot] of slots.entries()) {
+        next[slot] = moved[i];
+    }
+    return next;
+}
+/**
+ * Move the element at `idx` within `arr` in the given direction, returning a new
+ * array. An edge move (already at top/bottom) returns an unchanged copy.
+ */
+export function reorder(arr, idx, direction) {
+    const next = [...arr];
+    if (idx >= 0 && idx < arr.length) {
+        const [item] = next.splice(idx, 1);
+        const target = direction === 'up'
+            ? Math.max(0, idx - 1)
+            : direction === 'down'
+                ? Math.min(arr.length - 1, idx + 1)
+                : direction === 'top'
+                    ? 0
+                    : arr.length - 1;
+        next.splice(target, 0, item);
+    }
+    return next;
+}
+/**
+ * Put the elements whose id appears in `ids` into that relative order, leaving
+ * every other element in its own slot.
+ *
+ * The same slot permutation `reorderWithin` performs, driven by a stated order
+ * rather than by a direction. It exists because an order can arrive in another
+ * vocabulary entirely — a session spec's `layout` names views per panel, top to
+ * bottom — and there is one list that order has to land in.
+ *
+ * Elements named in `ids` but absent from `arr` are ignored, so a layout may
+ * name a view that failed to open.
+ */
+export function applyOrderWithin(arr, ids, getId) {
+    const rank = new Map(ids.map((id, i) => [id, i]));
+    const slots = [];
+    for (const [i, item] of arr.entries()) {
+        if (rank.has(getId(item))) {
+            slots.push(i);
+        }
+    }
+    const ordered = slots
+        .map(i => arr[i])
+        .sort((a, b) => rank.get(getId(a)) - rank.get(getId(b)));
+    const next = [...arr];
+    for (const [i, slot] of slots.entries()) {
+        next[slot] = ordered[i];
+    }
+    return next;
+}

package/esm/util/resolveRowHeight.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Resolve a multi-row display's raw `rowHeight` setting, where `0` is the
+ * fit-to-display-height sentinel, into the px height consumers actually draw
+ * with and divide by. The other half of the contract `applyRowResizeWheel` and
+ * tree-sidebar's `TreeDrawingModel` both spell `effectiveRowHeight` — see
+ * agent-docs/reference/ROW_HEIGHT_AND_FIT.md.
+ *
+ * Two rules, and they pull in opposite directions, which is why they live here
+ * rather than being restated per display:
+ *
+ * - **A sub-pixel fit height is legitimate and must pass through.** A cohort
+ *   with more rows than the display has pixels genuinely has a fractional row
+ *   height, and flooring it makes the content taller than the height it was
+ *   asked to fit inside — which re-grows the track and makes fit mode report a
+ *   scroll it is documented never to have. (2000 species floored to 1px re-grew
+ *   a MAF track to 2045px; the same regression hit the variant displays.) So
+ *   `autoRowHeight` itself is never floored.
+ * - **The resolved value must never be non-positive.** Consumers divide by it
+ *   (`rowAtY`, the hit tests, the renderers), so a `0` propagates NaN/Infinity.
+ *   A rows viewport can legitimately reach 0px — the variant matrix's
+ *   connector-line zone can swallow the whole display height — so this is
+ *   reachable, and it is the one place the floor belongs.
+ *
+ * Multi-wiggle is always-fit and has no sentinel to resolve, so it computes its
+ * `effectiveRowHeight` directly rather than calling this.
+ */
+export declare function resolveRowHeight(rowHeight: number, autoRowHeight: number): number;

package/esm/util/resolveRowHeight.js

@@ -0,0 +1,30 @@
+/**
+ * Resolve a multi-row display's raw `rowHeight` setting, where `0` is the
+ * fit-to-display-height sentinel, into the px height consumers actually draw
+ * with and divide by. The other half of the contract `applyRowResizeWheel` and
+ * tree-sidebar's `TreeDrawingModel` both spell `effectiveRowHeight` — see
+ * agent-docs/reference/ROW_HEIGHT_AND_FIT.md.
+ *
+ * Two rules, and they pull in opposite directions, which is why they live here
+ * rather than being restated per display:
+ *
+ * - **A sub-pixel fit height is legitimate and must pass through.** A cohort
+ *   with more rows than the display has pixels genuinely has a fractional row
+ *   height, and flooring it makes the content taller than the height it was
+ *   asked to fit inside — which re-grows the track and makes fit mode report a
+ *   scroll it is documented never to have. (2000 species floored to 1px re-grew
+ *   a MAF track to 2045px; the same regression hit the variant displays.) So
+ *   `autoRowHeight` itself is never floored.
+ * - **The resolved value must never be non-positive.** Consumers divide by it
+ *   (`rowAtY`, the hit tests, the renderers), so a `0` propagates NaN/Infinity.
+ *   A rows viewport can legitimately reach 0px — the variant matrix's
+ *   connector-line zone can swallow the whole display height — so this is
+ *   reachable, and it is the one place the floor belongs.
+ *
+ * Multi-wiggle is always-fit and has no sentinel to resolve, so it computes its
+ * `effectiveRowHeight` directly rather than calling this.
+ */
+export function resolveRowHeight(rowHeight, autoRowHeight) {
+    const height = rowHeight === 0 ? autoRowHeight : rowHeight;
+    return height > 0 ? height : 1;
+}

package/esm/util/revlist.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Flip a list of intervals onto the opposite strand of a `seqlen`-long
+ * sequence, returning them in ascending order. Every field other than
+ * start/end is carried through, so a CDS keeps its phase and type.
+ *
+ * Its own module because both the sequence helpers and `geneticCodes` need it,
+ * and `geneticCodes` importing `seqUtils` for it is what made the two mutually
+ * dependent — see the codon-table note in geneticCodes.ts.
+ */
+export declare function revlist<T extends {
+    start: number;
+    end: number;
+}>(list: T[], seqlen: number): T[];

package/esm/util/revlist.js

@@ -0,0 +1,14 @@
+/**
+ * Flip a list of intervals onto the opposite strand of a `seqlen`-long
+ * sequence, returning them in ascending order. Every field other than
+ * start/end is carried through, so a CDS keeps its phase and type.
+ *
+ * Its own module because both the sequence helpers and `geneticCodes` need it,
+ * and `geneticCodes` importing `seqUtils` for it is what made the two mutually
+ * dependent — see the codon-table note in geneticCodes.ts.
+ */
+export function revlist(list, seqlen) {
+    return list
+        .map(sub => ({ ...sub, start: seqlen - sub.end, end: seqlen - sub.start }))
+        .sort((a, b) => a.start - b.start);
+}

package/esm/util/rowStackGeometry.d.ts

@@ -0,0 +1,66 @@
+/**
+ * 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.
+ */
+export interface RowStack {
+    /** resolved height, never the 0/fit sentinel — this is divided into */
+    rowHeight: number;
+    /** unrounded, and routinely fractional */
+    scrollTop?: number;
+    /** chrome above the rows area, e.g. MAF's stacked bands */
+    topOffset?: number;
+}
+/** Content-space Y of the centre of the screen pixel `mouseY` is in. */
+export declare function contentYAt(mouseY: number, stack: RowStack): number;
+/** Continuous row coordinate at `mouseY`; callers round to suit. */
+export declare function rowCoordAt(mouseY: number, stack: RowStack): number;
+/** The row `mouseY` is on. Negative above the rows area, and not range-checked. */
+export declare function rowIndexAt(mouseY: number, stack: RowStack): number;
+/**
+ * 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 declare function rowSpanAt(y0: number, y1: number, stack: RowStack): {
+    startRow: number;
+    endRow: number;
+};
+/**
+ * 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 declare function rowsUnderPointer(mouseY: number, stack: RowStack, drawnRowHeight: number): {
+    nearest: number;
+    lowest: number;
+};

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,32 @@
 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 `signal` errors the subscriber with an abort error the moment it aborts,
+ * 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 `checkAbortSignal`
+ * 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>, signal?: AbortSignal): 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,91 @@
 import { Observable } from 'rxjs';
-export function ObservableCreate(func, _stopToken) {
+/**
+ * Wrapper for rxjs Observable.create with improved error handling and aborting
+ * support.
+ *
+ * A `signal` errors the subscriber with an abort error the moment it aborts,
+ * 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 `checkAbortSignal`
+ * ticks — but it does stop delivery downstream.
+ *
+ * @param func - observer function, could be async
+ */
+export function ObservableCreate(func, signal) {
     return new Observable((observer) => {
-        try {
-            const ret = func(observer);
-            if (ret?.catch) {
-                ret.catch((error) => {
-                    observer.error(error);
-                });
-            }
+        const stop = () => {
+            observer.error(signal?.reason);
+        };
+        if (signal?.aborted) {
+            // aborted 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);
+        };
+    });
+}
+/**
+ * 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/samplesTsv.d.ts

@@ -0,0 +1,49 @@
+import type PluginManager from '../PluginManager.ts';
+import type { BaseOptions } from '../data_adapters/BaseAdapter/types.ts';
+import type { FileLocation } from './types/data.ts';
+export type SamplesTsvRow = Record<string, string> & {
+    name: string;
+};
+export interface SamplesTsvResult {
+    sources: SamplesTsvRow[];
+    warnings: string[];
+}
+export declare const samplesTsvAdapterConfigSchemaFields: {
+    /**
+     * #slot
+     */
+    readonly samplesTsvLocation: {
+        readonly type: 'maybeFileLocation';
+        readonly description: "optional tab-separated table of per-sample metadata. It needs a header row, and its first column is the sample name exactly as the adapter spells it: a VCF sample, a MultiWiggle subtrack's name, a MAF species id. Every other column (`population`, `tissue`, ...) becomes an attribute of that sample, which the multi-row displays group, sort, color and tooltip rows by; a MAF adapter reads the `label`, `color` and `assemblyName` columns onto its species rows, over its `samples` entries. The table also narrows the adapter's samples to the ones it lists, and a table naming none of them is an error. An adapter that lists no samples of its own (a MAF track discovering its species from the file) takes the table's rows as its samples";
+    };
+};
+/**
+ * The metadata rows for the samples an adapter names, plus a warning for the
+ * samples the table leaves out, which no row is drawn for. Rows naming samples
+ * the adapter lacks are dropped silently: one project-wide table serving
+ * several tracks is the normal shape. `names` undefined means the adapter lists
+ * no samples of its own, so the rows become the set.
+ *
+ * A table matching none of `names` throws. Falling back to `names` would show
+ * every sample when the config asked for a curated subset, and an empty result
+ * draws a blank track with no banner. The message quotes both sides of the
+ * mismatch, because a prefix is what separates `1000GP_HG00096` from
+ * `HG00096`.
+ *
+ * `fileLabel` names the file in a message; `namesLabel` names where `names`
+ * came from ("the VCF").
+ */
+export declare function parseSamplesTsv(txt: string, names: readonly string[] | undefined, fileLabel: string, namesLabel: string): SamplesTsvResult;
+/**
+ * An adapter's samples merged with its `samplesTsvLocation` table: the bare
+ * `names` when the slot is unset, otherwise {@link parseSamplesTsv}'s rows.
+ * The warnings come back rather than going to `console.warn`, because this runs
+ * in a worker whose console nobody reads.
+ */
+export declare function getSamplesTsvSources({ location, names, namesLabel, pluginManager, opts, }: {
+    location: FileLocation | undefined;
+    names: readonly string[] | undefined;
+    namesLabel: string;
+    pluginManager?: PluginManager;
+    opts?: BaseOptions;
+}): Promise<SamplesTsvResult>;

package/esm/util/samplesTsv.js

@@ -0,0 +1,86 @@
+import { fetchAndMaybeUnzipText } from './fetchAndMaybeUnzip.js';
+import { getFileName } from './getFileName.js';
+import { openLocation } from './io/index.js';
+import { shorten2 } from './stringUtils.js';
+export const samplesTsvAdapterConfigSchemaFields = {
+    /**
+     * #slot
+     */
+    samplesTsvLocation: {
+        type: 'maybeFileLocation',
+        description: "optional tab-separated table of per-sample metadata. It needs a header row, and its first column is the sample name exactly as the adapter spells it: a VCF sample, a MultiWiggle subtrack's name, a MAF species id. Every other column (`population`, `tissue`, ...) becomes an attribute of that sample, which the multi-row displays group, sort, color and tooltip rows by; a MAF adapter reads the `label`, `color` and `assemblyName` columns onto its species rows, over its `samples` entries. The table also narrows the adapter's samples to the ones it lists, and a table naming none of them is an error. An adapter that lists no samples of its own (a MAF track discovering its species from the file) takes the table's rows as its samples",
+    },
+};
+/**
+ * The metadata rows for the samples an adapter names, plus a warning for the
+ * samples the table leaves out, which no row is drawn for. Rows naming samples
+ * the adapter lacks are dropped silently: one project-wide table serving
+ * several tracks is the normal shape. `names` undefined means the adapter lists
+ * no samples of its own, so the rows become the set.
+ *
+ * A table matching none of `names` throws. Falling back to `names` would show
+ * every sample when the config asked for a curated subset, and an empty result
+ * draws a blank track with no banner. The message quotes both sides of the
+ * mismatch, because a prefix is what separates `1000GP_HG00096` from
+ * `HG00096`.
+ *
+ * `fileLabel` names the file in a message; `namesLabel` names where `names`
+ * came from ("the VCF").
+ */
+export function parseSamplesTsv(txt, names, fileLabel, namesLabel) {
+    const lines = txt.split(/\n|\r\n|\r/);
+    const header = lines[0].split('\t');
+    const metadataSet = new Set();
+    const duplicates = new Set();
+    const metadataLines = lines
+        .slice(1)
+        .filter(Boolean)
+        .map(line => {
+        const [name, ...rest] = line.split('\t');
+        return {
+            ...Object.fromEntries(header.slice(1).map((col, idx) => [col, rest[idx] ?? ''])),
+            name: name,
+        };
+    })
+        .filter(row => {
+        if (metadataSet.has(row.name)) {
+            duplicates.add(row.name);
+            return false;
+        }
+        metadataSet.add(row.name);
+        return true;
+    });
+    const warnings = [];
+    if (duplicates.size) {
+        warnings.push(`${duplicates.size} samples appear more than once in the metadata file ${fileLabel}; the first row of each is used: ${shorten2([...duplicates].join(','))}`);
+    }
+    if (!names) {
+        return { sources: metadataLines, warnings };
+    }
+    const nameSet = new Set(names);
+    const namesNotInMetadata = [...nameSet].filter(f => !metadataSet.has(f));
+    const sources = metadataLines.filter(f => nameSet.has(f.name));
+    if (sources.length === 0 && names.length > 0) {
+        const example = metadataLines[0]?.name;
+        throw new Error(example === undefined
+            ? `The samples metadata file ${fileLabel} has a header but no sample rows, so this track has no rows to draw`
+            : `No sample in the metadata file ${fileLabel} matches ${namesLabel}, so this track has no rows to draw: its first column reads "${example}" where ${namesLabel} names "${names[0]}". Check for an added prefix or suffix, or for the sample IDs being in a different column.`);
+    }
+    if (namesNotInMetadata.length) {
+        warnings.push(`${namesNotInMetadata.length} of the ${names.length} samples in ${namesLabel} are not in the metadata file ${fileLabel} (${metadataLines.length} lines) and are not shown: ${shorten2(namesNotInMetadata.join(','))}`);
+    }
+    return { sources, warnings };
+}
+/**
+ * An adapter's samples merged with its `samplesTsvLocation` table: the bare
+ * `names` when the slot is unset, otherwise {@link parseSamplesTsv}'s rows.
+ * The warnings come back rather than going to `console.warn`, because this runs
+ * in a worker whose console nobody reads.
+ */
+export async function getSamplesTsvSources({ location, names, namesLabel, pluginManager, opts, }) {
+    if (!location) {
+        return { sources: (names ?? []).map(name => ({ name })), warnings: [] };
+    }
+    const txt = await fetchAndMaybeUnzipText(openLocation(location, pluginManager), opts, 'Downloading sample metadata');
+    return parseSamplesTsv(txt, names, 'uri' in location ? location.uri : getFileName(location), namesLabel);
+}