@jbrowse/core 4.3.0 → 5.0.0-beta.10

package/esm/util/dataGridUtils.js

@@ -0,0 +1,36 @@
+import { coarseStripHTML } from './coarseStripHTML.js';
+import { getStr } from './getStr.js';
+import { measureText } from './measureText.js';
+import { max } from './numericUtils.js';
+// The @mui/x-data-grid helpers, kept out of the `util` barrel: they are the
+// barrel's only reason to reach @mui/x-data-grid, and the barrel is imported by
+// worker-side adapter code that renders no grid.
+// heuristic measurement for a column of a @mui/x-data-grid, pass in
+// values from a column
+export function measureGridWidth(elements, args) {
+    const { padding = 30, minWidth = 80, fontSize = 12, maxWidth = 1000, stripHTML = false, } = args ?? {};
+    return max(elements.map(element => {
+        const str = getStr(element);
+        const n = measureText(stripHTML ? coarseStripHTML(str) : str, fontSize);
+        return Math.min(Math.max(n + padding, minWidth), maxWidth);
+    }));
+}
+// Resolve a @mui/x-data-grid v9 selection model into the concrete set of
+// selected row ids. The model is either an explicit include-set or an
+// exclude-set (the header "select all" checkbox produces the latter, e.g.
+// {type:'exclude', ids:{}} meaning "everything selected"), so reading model.ids
+// directly silently drops select-all and inverts a select-all-then-deselect.
+export function resolveSelectedIds(model, allIds) {
+    if (model.type === 'exclude') {
+        const result = new Set();
+        for (const id of allIds) {
+            if (!model.ids.has(id)) {
+                result.add(id);
+            }
+        }
+        return result;
+    }
+    else {
+        return new Set(model.ids);
+    }
+}

package/esm/util/dedupe.js

@@ -1,3 +1,4 @@
+// from https://github.com/seriousManual/dedupe/blob/master/LICENSE
 export function dedupe(list, hasher = JSON.stringify) {
     const clone = [];
     const lookup = new Set();

package/esm/util/deepEqual.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Structural equality: identity for primitives, recursive comparison for
+ * arrays/objects. Key order doesn't matter, unlike a `JSON.stringify`
+ * compare — which also can't tell `NaN` from `null` and silently drops
+ * `undefined`-valued keys, so `{ a: 1, b: undefined }` and `{ a: 1 }` would
+ * read as equal.
+ */
+export declare function deepEqual(a: unknown, b: unknown): boolean;

package/esm/util/deepEqual.js

@@ -0,0 +1,22 @@
+import { isPlainObject } from './objectUtils.js';
+/**
+ * Structural equality: identity for primitives, recursive comparison for
+ * arrays/objects. Key order doesn't matter, unlike a `JSON.stringify`
+ * compare — which also can't tell `NaN` from `null` and silently drops
+ * `undefined`-valued keys, so `{ a: 1, b: undefined }` and `{ a: 1 }` would
+ * read as equal.
+ */
+export function deepEqual(a, b) {
+    if (a === b) {
+        return true;
+    }
+    if (Array.isArray(a) && Array.isArray(b)) {
+        return a.length === b.length && a.every((x, i) => deepEqual(x, b[i]));
+    }
+    if (isPlainObject(a) && isPlainObject(b)) {
+        const ak = Object.keys(a);
+        const bk = Object.keys(b);
+        return (ak.length === bk.length && ak.every(k => k in b && deepEqual(a[k], b[k])));
+    }
+    return false;
+}

package/esm/util/deepMerge.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Recursive merge of `override` onto `base`, where a nested plain object merges
+ * key by key and **an array replaces rather than concatenates**. Both operands
+ * are deep-cloned, so neither is aliased by the result — the theme defaults are
+ * a module-level constant and a shared nested reference would let one caller's
+ * merge corrupt every later one.
+ *
+ * Replacing arrays is the only behaviour any caller here wanted: `assemblyNames`
+ * on a multi-genome track has to become the contributed list, not
+ * `[thisAssembly, ...allAssemblies]`, and a theme that names its own array of
+ * anything means that array instead of the base's. It is also the reason this
+ * exists rather than calling `deepmerge`, whose first overload is
+ * `<T>(x: Partial<T>, y: Partial<T>) => T`: passed a `Record<string, unknown>`
+ * it inferred `T` from the index signature, erased the shape of the object
+ * literal being merged, and handed back something every caller re-narrowed by
+ * hand.
+ *
+ * Objects only — an array as `base` or `override` is not a case any caller has.
+ */
+export declare function deepMerge<T extends object>(base: T, override: object): T;

package/esm/util/deepMerge.js

@@ -0,0 +1,44 @@
+import { isPlainObject } from './objectUtils.js';
+function cloneValue(value) {
+    return Array.isArray(value)
+        ? value.map(cloneValue)
+        : isPlainObject(value)
+            ? Object.fromEntries(Object.entries(value).map(([k, v]) => [k, cloneValue(v)]))
+            : value;
+}
+/**
+ * Recursive merge of `override` onto `base`, where a nested plain object merges
+ * key by key and **an array replaces rather than concatenates**. Both operands
+ * are deep-cloned, so neither is aliased by the result — the theme defaults are
+ * a module-level constant and a shared nested reference would let one caller's
+ * merge corrupt every later one.
+ *
+ * Replacing arrays is the only behaviour any caller here wanted: `assemblyNames`
+ * on a multi-genome track has to become the contributed list, not
+ * `[thisAssembly, ...allAssemblies]`, and a theme that names its own array of
+ * anything means that array instead of the base's. It is also the reason this
+ * exists rather than calling `deepmerge`, whose first overload is
+ * `<T>(x: Partial<T>, y: Partial<T>) => T`: passed a `Record<string, unknown>`
+ * it inferred `T` from the index signature, erased the shape of the object
+ * literal being merged, and handed back something every caller re-narrowed by
+ * hand.
+ *
+ * Objects only — an array as `base` or `override` is not a case any caller has.
+ */
+export function deepMerge(base, override) {
+    const merged = {};
+    for (const [key, value] of Object.entries(base)) {
+        merged[key] = cloneValue(value);
+    }
+    for (const [key, value] of Object.entries(override)) {
+        const existing = merged[key];
+        merged[key] =
+            isPlainObject(existing) && isPlainObject(value)
+                ? deepMerge(existing, value)
+                : cloneValue(value);
+    }
+    // `merged` already holds a cloned copy of every string key `base` has, so the
+    // base spread is what keeps the result typed as `T` without a cast — the one
+    // thing it contributes at runtime is any symbol key, which neither loop sees.
+    return { ...base, ...merged };
+}

package/esm/util/diagonalizeRegions.d.ts

@@ -0,0 +1,22 @@
+import type { StatusCallback } from './progress.ts';
+import type { Region } from './types/data.ts';
+export interface AlignmentData {
+    refRefName: string;
+    queryRefName: string;
+    refStart: number;
+    refEnd: number;
+    queryStart: number;
+    queryEnd: number;
+    strand: number;
+}
+export interface DiagonalizationResult {
+    newRegions: Region[];
+    stats: {
+        regionsReordered: number;
+        regionsReversed: number;
+    };
+}
+export declare function diagonalizeRegions(alignments: AlignmentData[], referenceRegions: Region[], currentRegions: Region[], { signal, statusCallback, }?: {
+    signal?: AbortSignal;
+    statusCallback?: StatusCallback;
+}): Promise<DiagonalizationResult>;

package/esm/util/diagonalizeRegions.js

@@ -0,0 +1,187 @@
+import { checkAbortSignal } from './aborting.js';
+import { cmpStr } from './cmpStr.js';
+import { createProgressReporter } from './progress.js';
+// A strand vote at least this lopsided (80% of aligned bases agreeing) decides
+// the reversal by itself. Below that the vote is unreliable: a chromosome
+// carrying many inversions splits it near 50/50, and MCScan `strand` is the
+// product of two gene strands rather than a block orientation. The ref-vs-query
+// position covariance then decides instead, which is the question reversal is
+// actually trying to answer (does the panel read monotonically along the
+// reference).
+const decisiveStrandFraction = 0.6;
+// Position along the anchor reference chromosome, and whether the query
+// chromosome should be displayed reversed.
+//
+// Summing in a fixed intra-pair order is what makes the result deterministic:
+// the synteny worker emits alignments in nondeterministic order (features from
+// concurrently-resolved blocks are concatenated by arrival, not position) and
+// float addition is non-associative, so a varying order would perturb these sums
+// in their low bits and could flip the query-chromosome ordering on a near-tie.
+// Only intra-pair order matters, since every sum here is over one pair.
+function anchorStats({ alignments, bases, strandWeightedSum }) {
+    alignments.sort((a, b) => a.refStart - b.refStart ||
+        a.queryStart - b.queryStart ||
+        a.refEnd - b.refEnd ||
+        a.queryEnd - b.queryEnd);
+    // x-axis (reference) length weights everything: consistent weighting for
+    // x-axis position and base count, matching the original jmonlong R
+    // implementation
+    let refPosSum = 0;
+    let queryPosSum = 0;
+    for (const aln of alignments) {
+        const alnLength = aln.refEnd - aln.refStart;
+        refPosSum += ((aln.refStart + aln.refEnd) / 2) * alnLength;
+        queryPosSum += ((aln.queryStart + aln.queryEnd) / 2) * alnLength;
+    }
+    const refMean = refPosSum / bases;
+    const queryMean = queryPosSum / bases;
+    // length-weighted covariance of the two axes' positions, centered on the means
+    // so it stays precise at genomic magnitudes. Negative means the query runs
+    // antiparallel to the reference.
+    let covariance = 0;
+    for (const aln of alignments) {
+        covariance +=
+            (aln.refEnd - aln.refStart) *
+                ((aln.refStart + aln.refEnd) / 2 - refMean) *
+                ((aln.queryStart + aln.queryEnd) / 2 - queryMean);
+    }
+    const strandFraction = strandWeightedSum / bases;
+    return {
+        bestRefPos: refMean,
+        shouldReverse: Math.abs(strandFraction) > decisiveStrandFraction || covariance === 0
+            ? strandFraction < 0
+            : covariance < 0,
+    };
+}
+// Groups alignments by vertical-axis (query) chromosome, accumulates total
+// aligned bases and strand per (query, reference) pair. Selects the reference
+// chromosome with the most aligned bases as the anchor, then sorts query
+// chromosomes to follow that reference's order, reversing a query chromosome
+// that runs antiparallel to its anchor.
+//
+// - refRefName:   horizontal-axis (reference) chromosome
+// - queryRefName: vertical-axis (query) chromosome
+export async function diagonalizeRegions(alignments, referenceRegions, currentRegions, { signal, statusCallback, } = {}) {
+    // Two reporters because the phases count different things (alignments, then
+    // chromosomes). No breakpoint: each pass measured ~50ms over 500k alignments.
+    const reportGrouping = createProgressReporter({
+        label: 'Ordering chromosomes',
+        total: alignments.length,
+        statusCallback,
+        signal,
+    });
+    // first appearance wins: a refName can appear in more than one reference
+    // region, and the ordering key is where that chromosome starts on the axis
+    const refOrder = new Map();
+    for (const [i, region] of referenceRegions.entries()) {
+        if (!refOrder.has(region.refName)) {
+            refOrder.set(region.refName, i);
+        }
+    }
+    // outer key: vertical chrom; inner key: horizontal chrom. Alignments to a
+    // reference chromosome the axis does not display are skipped: they can supply
+    // neither an ordering index nor a comparable position.
+    const queryGroups = new Map();
+    for (const aln of alignments) {
+        reportGrouping();
+        const refIndex = refOrder.get(aln.refRefName);
+        if (refIndex !== undefined) {
+            let group = queryGroups.get(aln.queryRefName);
+            if (!group) {
+                group = new Map();
+                queryGroups.set(aln.queryRefName, group);
+            }
+            let data = group.get(aln.refRefName);
+            if (!data) {
+                data = {
+                    refName: aln.refRefName,
+                    refIndex,
+                    bases: 0,
+                    strandWeightedSum: 0,
+                    alignments: [],
+                };
+                group.set(aln.refRefName, data);
+            }
+            const alnLength = aln.refEnd - aln.refStart;
+            data.bases += alnLength;
+            data.strandWeightedSum += (aln.strand >= 0 ? 1 : -1) * alnLength;
+            data.alignments.push(aln);
+        }
+    }
+    const queryOrdering = [];
+    const reportOrdering = createProgressReporter({
+        label: 'Ordering chromosomes',
+        total: queryGroups.size,
+        statusCallback,
+        signal,
+    });
+    for (const [verticalChrom, group] of queryGroups) {
+        reportOrdering();
+        let best;
+        for (const data of group.values()) {
+            // the refName tiebreak is explicit because Map iteration follows insertion
+            // order, which follows the order alignments arrived in
+            if (!best ||
+                data.bases > best.bases ||
+                (data.bases === best.bases && cmpStr(data.refName, best.refName) < 0)) {
+                best = data;
+            }
+        }
+        // bases === 0 means every alignment was zero-length, leaving no position to
+        // order by, so such a chromosome joins the unaligned tail below
+        if (best !== undefined && best.bases > 0) {
+            queryOrdering.push({
+                refName: verticalChrom,
+                bestRefIndex: best.refIndex,
+                ...anchorStats(best),
+            });
+        }
+    }
+    checkAbortSignal(signal);
+    queryOrdering.sort((a, b) => a.bestRefIndex - b.bestRefIndex ||
+        a.bestRefPos - b.bestRefPos ||
+        cmpStr(a.refName, b.refName));
+    // group by refName: a refName can appear in more than one region (e.g. a
+    // chromosome displayed in multiple regions), and all of them move together
+    const regionsByName = new Map();
+    for (const region of currentRegions) {
+        let group = regionsByName.get(region.refName);
+        if (!group) {
+            group = [];
+            regionsByName.set(region.refName, group);
+        }
+        group.push(region);
+    }
+    const orderedNames = new Set(queryOrdering.map(q => q.refName));
+    const newQueryRegions = [];
+    let regionsReversed = 0;
+    for (const { refName, shouldReverse } of queryOrdering) {
+        for (const region of regionsByName.get(refName) ?? []) {
+            newQueryRegions.push({ ...region, reversed: shouldReverse });
+            if (shouldReverse !== (region.reversed ?? false)) {
+                regionsReversed++;
+            }
+        }
+    }
+    // Regions with no alignments are appended after the ordered ones
+    const regionsWithoutAlignments = currentRegions.filter(r => !orderedNames.has(r.refName));
+    // Count how many regions ended up at a different position than they started
+    // (within the subset that participated in the ordering — unaligned regions
+    // keep their tail position and aren't counted as moves).
+    const previousOrder = currentRegions
+        .map(r => r.refName)
+        .filter(name => orderedNames.has(name));
+    let regionsReordered = 0;
+    for (let i = 0; i < newQueryRegions.length; i++) {
+        if (newQueryRegions[i].refName !== previousOrder[i]) {
+            regionsReordered++;
+        }
+    }
+    return {
+        newRegions: [...newQueryRegions, ...regionsWithoutAlignments],
+        stats: {
+            regionsReordered,
+            regionsReversed,
+        },
+    };
+}

package/esm/util/environment.d.ts

@@ -0,0 +1,4 @@
+export declare const isElectron: boolean;
+export declare const isNode: boolean;
+export declare function indexedDBAvailable(): boolean;
+export declare const rIC: ((cb: () => void) => void) | (((callback: IdleRequestCallback, options?: IdleRequestOptions) => number) & typeof requestIdleCallback);

package/esm/util/environment.js

@@ -0,0 +1,43 @@
+// Which JS environment we are running in, plus the idle-callback shim that
+// depends on it. Deliberately dependency-free and separate from the `util`
+// barrel: `util/io` needs `isElectron`/`isNode`, and importing them from the
+// barrel dragged the whole of `@jbrowse/core/util` — MST, the configuration
+// system, MUI — into anything that opened a file.
+export const isElectron = /electron/i.test(typeof navigator !== 'undefined' ? navigator.userAgent : '');
+// equivalent to the `detect-node` package: true only inside a real Node.js
+// process, not in browsers where `process` may be polyfilled by the bundler
+// (the toString brand is '[object process]' only for the genuine global).
+// `process` isn't in core's browser-targeted build lib, so read it off
+// globalThis rather than referencing the bare global
+export const isNode = Object.prototype.toString.call(globalThis.process) === '[object process]';
+// Whether there is an IndexedDB to open. The two callers gate on it rather than
+// catching, so the absence stays silent: opening it anyway throws a
+// ReferenceError that reads like a real failure, and that is the reason every
+// test run had to filter "indexedDB" out of console.error wholesale.
+//
+// Guarded like the Web Storage globals (see util/webStorage.ts): a bare
+// `typeof indexedDB` invokes the same getter, which throws rather than answering
+// in a cross-origin iframe with third-party storage blocked. So the probe that
+// exists to avoid a throw was itself the throw, in the one environment where it
+// matters — an embedded product on someone else's page.
+export function indexedDBAvailable() {
+    try {
+        return typeof indexedDB !== 'undefined';
+    }
+    catch {
+        return false;
+    }
+}
+// the real idle callback where the realm has one, otherwise a short timeout.
+// jsdom has neither, so tests install a synchronous shim
+// (config/jest/requestIdleCallback.js) rather than this branching on the
+// environment
+export const rIC = 
+// eslint-disable-next-line @typescript-eslint/no-unnecessary-condition
+typeof window !== 'undefined' && window.requestIdleCallback
+    ? window.requestIdleCallback
+    : (cb) => {
+        setTimeout(() => {
+            cb();
+        }, 1);
+    };

package/esm/util/eventPoint.d.ts

@@ -0,0 +1,32 @@
+/**
+ * A mouse event's position in the coordinate space of the element the handler
+ * is bound to.
+ *
+ * Off `currentTarget`, so there is no ref to thread and no way to measure
+ * against an element other than the one that received the event — which is the
+ * mistake this replaces. Five display handlers spelled the same three lines out,
+ * in three spellings, and each was one edit from measuring against a box the
+ * pointer was not in.
+ *
+ * **Read it during the handler.** React clears `currentTarget` once the handler
+ * returns, so a deferred read (an rAF, a promise) measures `null`.
+ *
+ * Two neighbours do a deliberately different thing, and neither is a candidate
+ * for this:
+ *
+ * - `getRelativeX` measures against an element passed in, because a rubberband
+ *   drag tracks the pointer across the whole document and the box it projects
+ *   through is not whatever is under the cursor.
+ * - A display whose canvas is a borderless leaf element (the pileup) reads
+ *   `offsetX`/`offsetY` off the native event, which is already this and costs no
+ *   layout read. That only holds while nothing is drawn inside the element, so
+ *   it is a fact about that canvas rather than a style to copy.
+ */
+export declare function eventPoint(event: {
+    clientX: number;
+    clientY: number;
+    currentTarget: Element;
+}): {
+    x: number;
+    y: number;
+};

package/esm/util/eventPoint.js

@@ -0,0 +1,28 @@
+/**
+ * A mouse event's position in the coordinate space of the element the handler
+ * is bound to.
+ *
+ * Off `currentTarget`, so there is no ref to thread and no way to measure
+ * against an element other than the one that received the event — which is the
+ * mistake this replaces. Five display handlers spelled the same three lines out,
+ * in three spellings, and each was one edit from measuring against a box the
+ * pointer was not in.
+ *
+ * **Read it during the handler.** React clears `currentTarget` once the handler
+ * returns, so a deferred read (an rAF, a promise) measures `null`.
+ *
+ * Two neighbours do a deliberately different thing, and neither is a candidate
+ * for this:
+ *
+ * - `getRelativeX` measures against an element passed in, because a rubberband
+ *   drag tracks the pointer across the whole document and the box it projects
+ *   through is not whatever is under the cursor.
+ * - A display whose canvas is a borderless leaf element (the pileup) reads
+ *   `offsetX`/`offsetY` off the native event, which is already this and costs no
+ *   layout read. That only holds while nothing is drawn inside the element, so
+ *   it is a fact about that canvas rather than a style to copy.
+ */
+export function eventPoint(event) {
+    const rect = event.currentTarget.getBoundingClientRect();
+    return { x: event.clientX - rect.left, y: event.clientY - rect.top };
+}

package/esm/util/expandLooseSearchIndex.d.ts

@@ -0,0 +1,19 @@
+/**
+ * A search index as a config may write it: the whole adapter config, or just
+ * the `.ix` that `jbrowse text-index` wrote, as a string or as `{ uri }`.
+ */
+export type LooseSearchIndex = string | {
+    uri: string;
+    baseUri?: string;
+    assemblyNames?: string[];
+} | {
+    type: string;
+    [key: string]: unknown;
+};
+/**
+ * Fill in what a search index written short leaves out: a string is its `uri`,
+ * `type` comes from a `uri` naming a `.ix`, and `assemblyNames` from the caller
+ * — the track's own for a per-track index, or a config's only assembly. A key
+ * already written is kept.
+ */
+export declare function expandLooseSearchIndex(snap: unknown, assemblyNames?: unknown): unknown;

package/esm/util/expandLooseSearchIndex.js

@@ -0,0 +1,29 @@
+function isTrixUri(uri) {
+    return /\.ix$/i.test(uri.split(/[?#]/)[0]);
+}
+/**
+ * Fill in what a search index written short leaves out: a string is its `uri`,
+ * `type` comes from a `uri` naming a `.ix`, and `assemblyNames` from the caller
+ * — the track's own for a per-track index, or a config's only assembly. A key
+ * already written is kept.
+ */
+export function expandLooseSearchIndex(snap, assemblyNames) {
+    const index = typeof snap === 'string' ? { uri: snap } : snap;
+    if (typeof index !== 'object' || index === null || Array.isArray(index)) {
+        return snap;
+    }
+    const entry = index;
+    const guessType = entry.type === undefined &&
+        typeof entry.uri === 'string' &&
+        isTrixUri(entry.uri);
+    const fillNames = entry.assemblyNames === undefined &&
+        Array.isArray(assemblyNames) &&
+        assemblyNames.length > 0;
+    return guessType || fillNames || index !== snap
+        ? {
+            ...entry,
+            ...(guessType ? { type: 'TrixTextSearchAdapter' } : {}),
+            ...(fillNames ? { assemblyNames } : {}),
+        }
+        : snap;
+}