@jbrowse/core 4.3.0 → 5.0.0-beta.10

package/esm/util/bandHeight.d.ts

@@ -0,0 +1,63 @@
+export declare const MIN_BAND_HEIGHT = 20;
+/** The legal range for one band. Both ends are optional and both are px. */
+export interface BandBounds {
+    /** Defaults to {@link MIN_BAND_HEIGHT}. */
+    min?: number;
+    /** Defaults to unbounded. A band above a plot should always state one. */
+    max?: number;
+}
+/**
+ * #api core/util
+ * Bound a band height to its legal range — a config value, a menu choice, or a
+ * slider position, i.e. anywhere the number is being *stated* rather than
+ * dragged.
+ *
+ * The **floor** keeps the band operable at its smallest: for a drag-resized
+ * band that means keeping the handle grabbable, for a menu-sized one it is the
+ * height below which its content stops reading. The **ceiling** stops a band
+ * from swallowing the plot it sits over — every display floors its plot area at
+ * 0, so an unbounded band takes the rows to zero height rather than to a
+ * scrollbar, and takes the band's own handle off-screen with them.
+ *
+ * The bounds differ per band and the rule does not, which is why this takes them
+ * rather than each band re-deriving the reasoning — that is how the two
+ * `clampBandHeight`s in this repo drifted apart, each ending up with one half of
+ * this rule and a doc comment claiming to be the whole of it.
+ */
+export declare function boundBandHeight(n: number, { min, max }?: BandBounds): number;
+/**
+ * #api core/util
+ * Clamp one *resize* of a drag-resizable band: {@link boundBandHeight}, plus the
+ * one rule a resize needs that a stated height does not.
+ *
+ * The floor becomes `min(bounds.min, current)`, never the bare bound: a band
+ * whose config declares it smaller than the floor must stay where it is. Taking
+ * the bare floor instead made the *first* drag on such a band jump it up to the
+ * floor before honoring the delta. A band at or above the floor is unaffected,
+ * one below it can still be dragged but never smaller than it already is, and
+ * one dragged back past the floor regains it.
+ *
+ * The ceiling is not relaxed the same way — a band already over its ceiling is
+ * the state the user is trying to escape, so a resize brings it back inside.
+ *
+ * `ResizeHandle` emits one delta per animation frame, so callers driving a drag
+ * pass `current + distance` as the target and read `current` inside the action —
+ * a component computing the target from a rendered height drops every tick that
+ * lands before React re-renders.
+ *
+ * @param current - the band's height right now, in px
+ * @param target - the height this resize is asking for, in px
+ * @param bounds - the band's legal range; `max` should be derived from the
+ *   display height so the plot below cannot be squashed to nothing
+ */
+export declare function clampBandHeight(current: number, target: number, bounds?: BandBounds): number;
+/**
+ * #api core/util
+ * Heights after growing or shrinking a stack of bands by `distance` px in all:
+ * the one rule every whole-stack resize uses. Each band takes its share of the
+ * height it has above `floor`, so the tall bands give and take the most, and
+ * none goes below `floor`, or below its own height if it already sits under it
+ * (the {@link clampBandHeight} rule). Whole pixels, rounded by largest
+ * remainder, so the stack moves by exactly the rounded distance.
+ */
+export declare function scaleBandHeights(heights: number[], distance: number, floor?: number): number[];

package/esm/util/bandHeight.js

@@ -0,0 +1,85 @@
+// Default floor for a user-resizable band (an alignments coverage / arc /
+// sashimi band, a MAF coverage / conservation band), in px. It exists so the
+// drag handle stays grabbable, which is a constraint on dragging, not on what
+// config may declare. Bands with their own vocabulary of "too small" pass their
+// own (the variant lane's 8 is where a record stops reading as a mark).
+export const MIN_BAND_HEIGHT = 20;
+/**
+ * #api core/util
+ * Bound a band height to its legal range — a config value, a menu choice, or a
+ * slider position, i.e. anywhere the number is being *stated* rather than
+ * dragged.
+ *
+ * The **floor** keeps the band operable at its smallest: for a drag-resized
+ * band that means keeping the handle grabbable, for a menu-sized one it is the
+ * height below which its content stops reading. The **ceiling** stops a band
+ * from swallowing the plot it sits over — every display floors its plot area at
+ * 0, so an unbounded band takes the rows to zero height rather than to a
+ * scrollbar, and takes the band's own handle off-screen with them.
+ *
+ * The bounds differ per band and the rule does not, which is why this takes them
+ * rather than each band re-deriving the reasoning — that is how the two
+ * `clampBandHeight`s in this repo drifted apart, each ending up with one half of
+ * this rule and a doc comment claiming to be the whole of it.
+ */
+export function boundBandHeight(n, { min = MIN_BAND_HEIGHT, max = Number.POSITIVE_INFINITY } = {}) {
+    return Math.min(max, Math.max(min, Math.round(n)));
+}
+/**
+ * #api core/util
+ * Clamp one *resize* of a drag-resizable band: {@link boundBandHeight}, plus the
+ * one rule a resize needs that a stated height does not.
+ *
+ * The floor becomes `min(bounds.min, current)`, never the bare bound: a band
+ * whose config declares it smaller than the floor must stay where it is. Taking
+ * the bare floor instead made the *first* drag on such a band jump it up to the
+ * floor before honoring the delta. A band at or above the floor is unaffected,
+ * one below it can still be dragged but never smaller than it already is, and
+ * one dragged back past the floor regains it.
+ *
+ * The ceiling is not relaxed the same way — a band already over its ceiling is
+ * the state the user is trying to escape, so a resize brings it back inside.
+ *
+ * `ResizeHandle` emits one delta per animation frame, so callers driving a drag
+ * pass `current + distance` as the target and read `current` inside the action —
+ * a component computing the target from a rendered height drops every tick that
+ * lands before React re-renders.
+ *
+ * @param current - the band's height right now, in px
+ * @param target - the height this resize is asking for, in px
+ * @param bounds - the band's legal range; `max` should be derived from the
+ *   display height so the plot below cannot be squashed to nothing
+ */
+export function clampBandHeight(current, target, bounds = {}) {
+    const { min = MIN_BAND_HEIGHT } = bounds;
+    return boundBandHeight(target, { ...bounds, min: Math.min(min, current) });
+}
+/**
+ * #api core/util
+ * Heights after growing or shrinking a stack of bands by `distance` px in all:
+ * the one rule every whole-stack resize uses. Each band takes its share of the
+ * height it has above `floor`, so the tall bands give and take the most, and
+ * none goes below `floor`, or below its own height if it already sits under it
+ * (the {@link clampBandHeight} rule). Whole pixels, rounded by largest
+ * remainder, so the stack moves by exactly the rounded distance.
+ */
+export function scaleBandHeights(heights, distance, floor = MIN_BAND_HEIGHT) {
+    const floors = heights.map(h => Math.min(h, floor));
+    const room = heights.map((h, i) => h - floors[i]);
+    const roomTotal = room.reduce((a, b) => a + b, 0);
+    const target = Math.max(0, Math.round(roomTotal + distance));
+    const exact = room.map(r => roomTotal > 0 ? (r * target) / roomTotal : target / heights.length);
+    const whole = exact.map(e => Math.floor(e));
+    let left = target - whole.reduce((a, b) => a + b, 0);
+    const byRemainder = exact
+        .map((e, i) => ({ i, frac: e - whole[i] }))
+        .sort((a, b) => b.frac - a.frac);
+    for (const { i } of byRemainder) {
+        if (left <= 0) {
+            break;
+        }
+        whole[i] = whole[i] + 1;
+        left -= 1;
+    }
+    return whole.map((w, i) => w + floors[i]);
+}

package/esm/util/bandLayout.d.ts

@@ -0,0 +1,51 @@
+import type { BandBounds } from './bandHeight.ts';
+/**
+ * #api core/util
+ * One band of a display's vertical stack — a coverage histogram, an arc strip,
+ * a conservation row, a variant lane. The contract is the pair: `active` is
+ * whether the band exists right now (the display pre-ANDs its settings half,
+ * `showX`, with its data half, "some lane has ink"), and `height` is the stated
+ * height when it does. Consumers read pixels through {@link reservedPx} or
+ * {@link stackBands}, never by re-combining the pair — the re-combination is
+ * where the reserver and the painter historically drifted.
+ */
+export interface Band {
+    active: boolean;
+    /** The stated height in px, meaningful only while `active`. */
+    height: number;
+    /**
+     * Present ⇒ `height` is bound at read time ({@link boundBandHeight}), for a
+     * band whose stored value may be stale or hand-edited. Absent ⇒ the stated
+     * height is trusted as-is; the setters are the only gate.
+     */
+    bounds?: BandBounds;
+}
+/**
+ * #api core/util
+ * The pixels a band takes from the plot below it: 0 when off, the (optionally
+ * bound) stated height when on. This is the single spelling of "off spends
+ * 0 px".
+ */
+export declare function reservedPx(band: Band): number;
+/** What {@link stackBands} derives: one top per band, and where the stack ends. */
+export interface BandStack<K extends string> {
+    /** Content-space y where each band begins, in stack order. */
+    top: Record<K, number>;
+    /** Each band's {@link reservedPx}. */
+    reserved: Record<K, number>;
+    /** Where the content below the stack begins — the sum of every reserved px. */
+    bottom: number;
+}
+/**
+ * #api core/util
+ * Fold an ordered set of bands into tops and a bottom. The order is the
+ * argument, so a display states its band order exactly once. Reserve, paint
+ * and pick all call this function, so the reserved and painted positions
+ * cannot disagree.
+ *
+ * Only the fold is shared; the rest stays in each display. Per-lane
+ * iteration runs this once per lane, sticky-vs-scrolling is a property of how
+ * the result is projected to the screen, and a band drawn outside its
+ * reservation (an overlay) carries its own draw rect beside the stack.
+ */
+export declare function stackBands<K extends string>(order: readonly K[], bands: Record<K, Band>): BandStack<K>;

package/esm/util/bandLayout.js

@@ -0,0 +1,36 @@
+import { boundBandHeight } from './bandHeight.js';
+/**
+ * #api core/util
+ * The pixels a band takes from the plot below it: 0 when off, the (optionally
+ * bound) stated height when on. This is the single spelling of "off spends
+ * 0 px".
+ */
+export function reservedPx(band) {
+    if (!band.active) {
+        return 0;
+    }
+    return band.bounds ? boundBandHeight(band.height, band.bounds) : band.height;
+}
+/**
+ * #api core/util
+ * Fold an ordered set of bands into tops and a bottom. The order is the
+ * argument, so a display states its band order exactly once. Reserve, paint
+ * and pick all call this function, so the reserved and painted positions
+ * cannot disagree.
+ *
+ * Only the fold is shared; the rest stays in each display. Per-lane
+ * iteration runs this once per lane, sticky-vs-scrolling is a property of how
+ * the result is projected to the screen, and a band drawn outside its
+ * reservation (an overlay) carries its own draw rect beside the stack.
+ */
+export function stackBands(order, bands) {
+    const top = {};
+    const reserved = {};
+    let y = 0;
+    for (const key of order) {
+        top[key] = y;
+        reserved[key] = reservedPx(bands[key]);
+        y += reserved[key];
+    }
+    return { top, reserved, bottom: y };
+}

package/esm/util/bezierConnector.d.ts

@@ -0,0 +1,15 @@
+export declare const CUBIC_APEX_RATIO = 0.75;
+export declare const BEZIER_CONNECTOR_MAX_REACH_PX = 110;
+export declare function bezierConnectorPath({ x1, y1, x2, y2, s1, s2, leadingEnd2, reversed1, reversed2, maxHandlePx, dipPx, }: {
+    x1: number;
+    y1: number;
+    x2: number;
+    y2: number;
+    s1: number;
+    s2: number;
+    leadingEnd2?: boolean;
+    reversed1?: boolean;
+    reversed2?: boolean;
+    maxHandlePx?: number;
+    dipPx?: number;
+}): string;

package/esm/util/bezierConnector.js

@@ -0,0 +1,101 @@
+// One horizontal-tangent "oval" connector curve, shared by the alignments
+// linked-read bezier overlay (PileupBezierOverlay) and BreakpointSplitView's
+// AlignmentConnections so the two renderers draw a connection identically. Both
+// describe the same thing — two read endpoints (from the shared
+// connectionEndpoints rule), each segment's strand, and whether the second end
+// is a split junction's 5' edge — and this owns the curve geometry, so the
+// direction logic can't drift between them.
+// A handle or bow larger than the endpoints' own separation folds the cubic
+// back over itself: the curve leaves along its tangent, overshoots the far
+// endpoint, and has to curl back to arrive — the "loop-de-loop"/squiggle seen
+// on tightly-spaced reads. So every shaping term stays under this fraction of
+// the span the curve actually has to cover. Endpoints that nearly touch
+// therefore get no shaping at all and draw as the straight line they should be.
+const SPAN_FACTOR = 0.3;
+// Ceiling on the control-handle length. The span budget is what actually scales
+// the handle — it resolves below this for any connection whose endpoints are
+// closer than ~667px apart, which is nearly all of them — so this only bites on
+// very wide arcs. There it bounds the fold-back hook that an inversion draws at
+// its leading end: unbounded, that hook grows with the arc, and a full-width
+// inversion flings a ~500px curl back across unrelated reads.
+const MAX_HANDLE_PX = 200;
+// A symmetric cubic's extreme sits 3/4 of the way from its baseline to its
+// control points, so an arc asked to reach a given apex puts its controls 4/3
+// past it. Exported because the sashimi overlay solves the same equation in the
+// other direction, and the two spellings drifting apart would put the insert-
+// size ruler's labels at heights nothing plots at.
+export const CUBIC_APEX_RATIO = 0.75;
+// Vertical bow applied to a connection whose two endpoints share (or nearly
+// share) a row — e.g. a chain whose split segments are all laid out on one
+// pileup row. Without it the horizontal-only handles collapse the cubic to a
+// flat, invisible line lying on the row; the bow lifts the control points so
+// the curve arcs into a visible hump. This is the control-point lift, not the
+// height the curve reaches.
+const MAX_BOW_PX = 30;
+// A discordant connection bows *down* instead of up, so the two classes read
+// apart at a glance. Both renderers follow this: BreakpointSplitView dips its
+// same-level discordant links, and the pileup overlay dips every discordant
+// curve it draws (a normal-orientation pair is a plain line, or bows up over its
+// row where a hidden-segment one would lie on a chain's connecting line). Keep
+// it that way — a renderer that opts out makes "below the reads" mean two
+// different things in two views of the same data.
+//
+// HOW DEEP is the renderer's call, not this file's. Depth is the mark's one free
+// channel, and only the renderer knows the band the ink has to survive in — the
+// pileup clips each section at its band bottom, and the split view bleeds a
+// too-deep dip into the panel below. So callers pass the depth they want and
+// `discordantDipPx` (@jbrowse/sv-core) is the law the two of them share.
+// How far a curve can stray outside the band between its two endpoints. The dip
+// is the deeper of the two shaping terms, so this is a ceiling on it, applied
+// here rather than trusted to a caller: a culler pads its viewport test by this,
+// and the shaping is applied to the *control points*, so a curve whose two
+// endpoints both sit just outside the viewport can still have a visible body.
+export const BEZIER_CONNECTOR_MAX_REACH_PX = 110;
+// Sign (+1/-1) of an endpoint's horizontal control handle. The handle leaves a
+// trailing (3') endpoint along the read's reading direction (`strand`); at a
+// split junction's leading (5') endpoint it flips, so the curve arrives flowing
+// *into* the next segment (a fwd→rev inversion folds back instead of cutting
+// straight across). `reversed` flips screen-x for a reverse-complemented region.
+function tangentSign(strand, leading, reversed) {
+    return strand * (leading ? -1 : 1) * (reversed ? -1 : 1);
+}
+// How much shaping (handle length, bow height) this curve may spend: a fraction
+// of the distance it has to cover.
+function shapingBudget(p1, p2) {
+    return Math.hypot(p2.x - p1.x, p2.y - p1.y) * SPAN_FACTOR;
+}
+// Fades to zero as the endpoints' rows separate, since a cross-row curve
+// already has vertical extent — and via the budget as they close in
+// horizontally, since a short connector is legible without a hump.
+function bowHeight(p1, p2, budget) {
+    return Math.min(budget, Math.max(0, MAX_BOW_PX - Math.abs(p2.y - p1.y)));
+}
+function cubicPath(from, ctrl1, ctrl2, to) {
+    return `M ${from.x} ${from.y} C ${ctrl1.x} ${ctrl1.y} ${ctrl2.x} ${ctrl2.y} ${to.x} ${to.y}`;
+}
+export function bezierConnectorPath({ x1, y1, x2, y2, s1, s2, 
+// The second endpoint is a split junction's 5' leading edge (its handle flips
+// to fold the curve into the next segment); false for a paired mate's 3' edge.
+leadingEnd2 = false, reversed1 = false, reversed2 = false, maxHandlePx = MAX_HANDLE_PX, 
+// Depth, in px, of the dip a discordant connection draws instead of the bow a
+// concordant one gets — aberrant pair orientation, or a split junction's
+// strand flip, so the two classes are tellable apart by shape alone. It is
+// the depth of the curve's APEX — what a caller can bound by the room it has —
+// and CUBIC_APEX_RATIO converts it to the control-point drop that puts the ink
+// there. Leave it out to bow up.
+dipPx, }) {
+    const from = { x: x1, y: y1 };
+    const to = { x: x2, y: y2 };
+    const budget = shapingBudget(from, to);
+    const handle = Math.min(maxHandlePx, budget);
+    // The dip is deliberately not clamped to the budget, unlike the bow. The
+    // budget stops the cubic folding back over itself, and only the horizontal
+    // handles can do that — a vertical offset leaves x(t) monotonic however deep
+    // it goes, so a big event squeezed into a few px draws a narrow trough rather
+    // than a squiggle. Pinned by 'a dipped connection never overshoots its
+    // endpoints in x'.
+    const bow = dipPx === undefined
+        ? bowHeight(from, to, budget)
+        : -Math.min(dipPx, BEZIER_CONNECTOR_MAX_REACH_PX) / CUBIC_APEX_RATIO;
+    return cubicPath(from, { x: x1 + handle * tangentSign(s1, false, reversed1), y: y1 - bow }, { x: x2 + handle * tangentSign(s2, leadingEnd2, reversed2), y: y2 - bow }, to);
+}

package/esm/util/bgzfWorkerPool.d.ts

@@ -0,0 +1,24 @@
+import type { BgzfWorkerPool } from '@gmod/bgzf-filehandle';
+/**
+ * The BGZF inflate pool the indexed-format libraries decompress large chunks on,
+ * one per JS context like `decompressedBytesBudget`: one per RPC worker plus one
+ * on the main thread. BGZF decompression is 70-90% of a cold query (`@gmod/bam`
+ * ADR 0003), and its blocks inflate independently.
+ *
+ * Holding it costs nothing. `@gmod/bgzf-filehandle` 6.7 starts the workers only
+ * when a chunk of at least `POOL_MIN_DECOMPRESSED_BYTES` (0.4MB inflated)
+ * arrives, inflates in process while they boot, and inflates in process for good
+ * if one of them fails, so no read waits on a worker. What it is worth per
+ * format, and why GFF3 and GTF go without it: reference/BGZF_WORKER_POOL.md.
+ *
+ * A function over a dynamic import because the library inlines its worker bundle
+ * as a base64 string, and a static import pins it into every entry point that
+ * can reach this helper: measured with esbuild, 23.4kb gzipped against 141b. Test
+ * speed is not a reason either way; three jbrowse-web variant suites ran 13.887s
+ * static against 13.856s dynamic.
+ *
+ * Resolves to `undefined` wherever Workers cannot be created (node, jest), which
+ * keeps `@gmod/bam` and `@gmod/tabix` on their in-process path, and the `catch`
+ * keeps anything else going wrong here on it too.
+ */
+export declare function sharedBgzfWorkerPool(): Promise<BgzfWorkerPool | undefined>;

package/esm/util/bgzfWorkerPool.js

@@ -0,0 +1,27 @@
+/**
+ * The BGZF inflate pool the indexed-format libraries decompress large chunks on,
+ * one per JS context like `decompressedBytesBudget`: one per RPC worker plus one
+ * on the main thread. BGZF decompression is 70-90% of a cold query (`@gmod/bam`
+ * ADR 0003), and its blocks inflate independently.
+ *
+ * Holding it costs nothing. `@gmod/bgzf-filehandle` 6.7 starts the workers only
+ * when a chunk of at least `POOL_MIN_DECOMPRESSED_BYTES` (0.4MB inflated)
+ * arrives, inflates in process while they boot, and inflates in process for good
+ * if one of them fails, so no read waits on a worker. What it is worth per
+ * format, and why GFF3 and GTF go without it: reference/BGZF_WORKER_POOL.md.
+ *
+ * A function over a dynamic import because the library inlines its worker bundle
+ * as a base64 string, and a static import pins it into every entry point that
+ * can reach this helper: measured with esbuild, 23.4kb gzipped against 141b. Test
+ * speed is not a reason either way; three jbrowse-web variant suites ran 13.887s
+ * static against 13.856s dynamic.
+ *
+ * Resolves to `undefined` wherever Workers cannot be created (node, jest), which
+ * keeps `@gmod/bam` and `@gmod/tabix` on their in-process path, and the `catch`
+ * keeps anything else going wrong here on it too.
+ */
+export function sharedBgzfWorkerPool() {
+    return import('@gmod/bgzf-filehandle')
+        .then(m => m.getSharedWorkerPool())
+        .catch(() => undefined);
+}

package/esm/util/binnedAggregate.d.ts

@@ -0,0 +1,17 @@
+import type { AggregateStep, BinStep } from './markEncodingTypes.ts';
+import type { Staged } from './stepTables.ts';
+/**
+ * Whether an interval `bin` and the `aggregate` behind it run as one kernel:
+ * the aggregate groups by the bin's two edges, and every field it reads is a
+ * plain name, so a piece's value is its row's or one the bin wrote.
+ */
+export declare function fusesBinAggregate(bin: BinStep, agg: AggregateStep): boolean;
+/**
+ * An interval `bin` and the `aggregate` grouped by its edges as one walk: each
+ * row's bins accumulate straight into their group's sums, with no piece table,
+ * the way `binRawRegion` bins a BigWig's raw section. The groups come out in
+ * the order the pieces would have met them and each sum adds its pieces in
+ * the pieces' order, so the answer is the two steps' to the bit. Undefined
+ * where the bins spread too thinly over the region for a dense index.
+ */
+export declare function binnedAggregate({ table, bounds }: Staged, bin: BinStep, agg: AggregateStep): Staged | undefined;