@jbrowse/core 4.3.0 → 5.0.0-beta.1

package/esm/util/convertCodingSequenceToPeptides.js

@@ -1,10 +1,57 @@
-import { stitch } from "../BaseFeatureWidget/util.js";
-export function convertCodingSequenceToPeptides({ cds, sequence, codonTable, }) {
+import { stitch } from './seqUtils.js';
+// Maps a single position (in the same coordinate system as the cds array) to its
+// codon index within the stitched CDS string. Returns undefined if the position
+// falls outside all CDS segments or before the phase offset.
+function posToCodonIndex(pos, cds, phase) {
+    let offset = 0;
+    for (const seg of cds) {
+        if (pos >= seg.start && pos < seg.end) {
+            const stitchedPos = offset + (pos - seg.start);
+            if (stitchedPos < phase) {
+                return undefined;
+            }
+            return Math.floor((stitchedPos - phase) / 3);
+        }
+        offset += seg.end - seg.start;
+    }
+    return undefined;
+}
+// phase > 0 prepends a leading '&' to the protein, shifting every codon's index
+// in the protein string by one.
+function proteinIndexShift(phase) {
+    return phase > 0 ? 1 : 0;
+}
+// Maps each in-range transl_except to its codon index within the stitched CDS.
+function translExceptCodonOverrides(cds, translExcept, phase) {
+    const overrides = new Map();
+    for (const ex of translExcept) {
+        const idx = posToCodonIndex(ex.start, cds, phase);
+        if (idx !== undefined) {
+            overrides.set(idx, ex.aa);
+        }
+    }
+    return overrides;
+}
+// Returns the 0-indexed positions in the final protein string where translExcept
+// overrides were applied. Position 0 = first character of the returned protein string
+// (which may be '&' if phase > 0). Callers use this to highlight those characters.
+export function translExceptProteinPositions({ cds, translExcept = [], }) {
+    const phase = cds[0]?.phase ?? 0;
+    const shift = proteinIndexShift(phase);
+    const codonIndexes = translExceptCodonOverrides(cds, translExcept, phase).keys();
+    return new Set([...codonIndexes].map(idx => idx + shift));
+}
+export function convertCodingSequenceToPeptides({ cds, sequence, codonTable, starts, translExcept = [], }) {
     const phase = cds[0]?.phase ?? 0;
     const str = stitch(cds, sequence);
+    const overrides = translExceptCodonOverrides(cds, translExcept, phase);
     let protein = phase > 0 ? '&' : '';
-    for (let i = phase; i < str.length; i += 3) {
-        protein += codonTable[str.slice(i, i + 3)] || '&';
+    let codonIdx = 0;
+    for (let i = phase; i < str.length; i += 3, codonIdx++) {
+        const codon = str.slice(i, i + 3);
+        const isStart = codonIdx === 0 && phase === 0 && starts?.includes(codon.toUpperCase());
+        protein +=
+            overrides.get(codonIdx) ?? (isStart ? 'M' : codonTable[codon]) ?? '&';
     }
     return protein;
 }

package/esm/util/copyText.d.ts

@@ -0,0 +1,18 @@
+import type { CopyOptions } from './copyToClipboard.ts';
+import type { AbstractSessionModel } from './types/index.ts';
+import type { IAnyStateTreeNode } from '@jbrowse/mobx-state-tree';
+/**
+ * Copy `text` to the clipboard, confirming it in a snackbar (`what` names what
+ * landed — "read name", "EDEN.1:c.93+1", "feature info") and surfacing a failure
+ * rather than silently doing nothing.
+ *
+ * Every display that offered a copy item had grown its own copy of this wrapper,
+ * and they had drifted on both the wording and whether an error reached the user
+ * at all. Take this when you hold a session; `copyText` when you hold a model.
+ */
+export declare function copyTextWithSession(session: Pick<AbstractSessionModel, 'notify' | 'notifyError'>, text: string, what: string, options?: CopyOptions): Promise<void>;
+/**
+ * `copyTextWithSession` for a menu item on a model, which is what a display has
+ * in hand.
+ */
+export declare function copyText(node: IAnyStateTreeNode, text: string, what: string, options?: CopyOptions): Promise<void>;

package/esm/util/copyText.js

@@ -0,0 +1,30 @@
+import copyToClipboard from './copyToClipboard.js';
+import { getSession } from './mstUtils.js';
+/**
+ * Copy `text` to the clipboard, confirming it in a snackbar (`what` names what
+ * landed — "read name", "EDEN.1:c.93+1", "feature info") and surfacing a failure
+ * rather than silently doing nothing.
+ *
+ * Every display that offered a copy item had grown its own copy of this wrapper,
+ * and they had drifted on both the wording and whether an error reached the user
+ * at all. Take this when you hold a session; `copyText` when you hold a model.
+ */
+export async function copyTextWithSession(session, text, what, options) {
+    try {
+        // awaited: copyToClipboard reports a rejected write by throwing, so without
+        // this the snackbar confirms a copy that never landed
+        await copyToClipboard(text, options);
+        session.notify(`Copied ${what} to clipboard`, 'success');
+    }
+    catch (e) {
+        console.error(e);
+        session.notifyError(`${e}`, e);
+    }
+}
+/**
+ * `copyTextWithSession` for a menu item on a model, which is what a display has
+ * in hand.
+ */
+export async function copyText(node, text, what, options) {
+    return copyTextWithSession(getSession(node), text, what, options);
+}

package/esm/util/copyToClipboard.d.ts

@@ -0,0 +1,4 @@
+export interface CopyOptions {
+    format?: string;
+}
+export default function copyToClipboard(text: string, options?: CopyOptions): Promise<void>;

package/esm/util/copyToClipboard.js

@@ -0,0 +1,58 @@
+// Throws when the write did not happen, which is the only signal the async API
+// gives (it reports a denied permission or an unfocused document by rejecting).
+// A caller that reports success must therefore await this, or it confirms a copy
+// that never landed.
+export default async function copyToClipboard(text, options = {}) {
+    const format = options.format ?? 'text/plain';
+    // navigator.clipboard is only present in secure contexts; isSecureContext is
+    // the real gate, so insecure http:// falls through to execCommand below
+    if (format === 'text/plain' && window.isSecureContext) {
+        await navigator.clipboard.writeText(text);
+    }
+    else if (!execCommandCopy(text, format)) {
+        throw new Error('the browser rejected the clipboard write');
+    }
+}
+function execCommandCopy(text, format) {
+    const selection = document.getSelection();
+    const previousRange = selection && selection.rangeCount > 0 ? selection.getRangeAt(0) : undefined;
+    // offscreen span carrying the text, with whitespace preserved
+    const span = document.createElement('span');
+    span.textContent = text;
+    span.style.whiteSpace = 'pre';
+    span.style.position = 'fixed';
+    span.style.top = '0';
+    span.style.left = '0';
+    span.style.opacity = '0';
+    document.body.append(span);
+    const listener = (e) => {
+        if (e.clipboardData) {
+            e.clipboardData.clearData();
+            e.clipboardData.setData(format, text);
+        }
+        e.preventDefault();
+    };
+    document.addEventListener('copy', listener);
+    let success = false;
+    try {
+        const range = document.createRange();
+        range.selectNodeContents(span);
+        selection?.removeAllRanges();
+        selection?.addRange(range);
+        // execCommand is deprecated but is the only clipboard write available in
+        // non-secure (http://) contexts, which JBrowse must support
+        success = document.execCommand('copy');
+    }
+    catch (e) {
+        console.error(e);
+    }
+    finally {
+        document.removeEventListener('copy', listener);
+        selection?.removeAllRanges();
+        if (previousRange) {
+            selection?.addRange(previousRange);
+        }
+        span.remove();
+    }
+    return success;
+}

package/esm/util/createStopTokenRotation.d.ts

@@ -0,0 +1,117 @@
+import type { RpcStatus, StatusWindow } from './progress.ts';
+import type { StopToken } from './stopToken.ts';
+import type { IStateTreeNode } from '@jbrowse/mobx-state-tree';
+/**
+ * Where a rotation reports, in the one of two modes the host is actually in.
+ *
+ * A union rather than one shape with an optional window, because the two modes
+ * do not use the same member and the optional version required the one that is
+ * dead in the lending mode: when a host lends its `statusWindow` the rotation
+ * writes through the window and never calls `setStatusMessage`, so a caller
+ * supplying both got silence from the half it thought it was wiring up.
+ * `FetchMixin` was that caller.
+ */
+export type StatusReporter = {
+    /**
+     * The host's own window, present on any display composing the LGV fetch
+     * mixins. The rotation reports through it rather than opening a SECOND on
+     * the same status field — which is what one-window-per-owner exists to
+     * prevent.
+     */
+    statusWindow: StatusWindow;
+    setStatusMessage?: never;
+} | {
+    /**
+     * The sink for the window the rotation opens for itself. This is the mode
+     * the displays this helper was written for are in (dotplot, synteny),
+     * which compose no fetch mixin, along with every
+     * {@link createStatusChannel} holder.
+     */
+    setStatusMessage: (status?: RpcStatus) => void;
+    statusWindow?: never;
+};
+/**
+ * A {@link StatusReporter} a model can hold in **one** volatile, for something
+ * that has one operation to narrate and no reason to grow a status vocabulary
+ * of its own. `ProgressChip` takes `message`/`fraction` straight off it.
+ *
+ * The alternative is what every display does: two volatiles and an action
+ * calling {@link statusMessageText} and {@link statusFraction}. That is the
+ * right shape where the fields are part of the model's own surface —
+ * `BaseDisplay` and `FetchMixin` declare them because half the display API reads
+ * them — and a lot of declaration for a view that wants a corner chip while one
+ * fetch runs. A plain function rather than a mixin because a compose layer is
+ * what the model chains here cannot afford (ADR-041).
+ */
+export interface StatusChannel {
+    setStatusMessage: (status?: RpcStatus) => void;
+    readonly message: string | undefined;
+    readonly fraction: number | undefined;
+}
+export declare function createStatusChannel(): StatusChannel;
+export interface ActiveFetch {
+    /** stop token to forward to the RPC call */
+    stopToken: StopToken;
+    /**
+     * True only while this is still the most recent fetch AND `self` is alive.
+     * Gate every post-await write — result commit, error set — on it so a
+     * superseded or torn-down fetch never writes back.
+     */
+    isCurrent: () => boolean;
+    /**
+     * RPC `statusCallback` pre-gated by `isCurrent`: forwards progress to
+     * `setStatusMessage` only while this is still the latest fetch, so a
+     * superseded fetch's late status update can't flicker the overlay, and
+     * throttled to the same leading edge as `FetchMixin`'s callbacks. Pass it
+     * straight as the RPC `statusCallback` arg.
+     */
+    statusCallback: (status: RpcStatus) => void;
+    /**
+     * Call in the `finally` of the run that owns this fetch: closes `isCurrent`
+     * and retires this fetch's status slot, which blanks the field only if no
+     * other operation on the host is still reporting.
+     *
+     * Both together, because a caller doing it by hand gets a subset.
+     * `isCurrent` is `token === current && isAlive`, and a run that *completes*
+     * never rotates its own token — so without this the guard stays open past the
+     * work and a trailing write lands on top of a hand-written
+     * `setStatusMessage(undefined)` up to a window later.
+     *
+     * A **superseded** run calls it too, and must: its slot goes on voting for a
+     * phase that is over until it does. The run that replaced it has already
+     * opened its own slot by then, so the label the user is looking at survives.
+     */
+    end: () => void;
+}
+/**
+ * Latest-wins stop-token rotation for a fetch that runs in a bare `autorun`
+ * rather than through `FetchMixin.runFetch` (which welds the same mechanics to
+ * `fetchGeneration`, so it's only for viewport-driven LGV fetches). Each
+ * `begin()` aborts the prior fetch's token and returns a fresh one plus an
+ * `isCurrent()` guard that captures this run's token — gate every post-await
+ * write on it and a superseded or torn-down fetch can never clobber fresher
+ * data. The guard is the return value, so a caller can't forget to compare a
+ * token by hand.
+ *
+ * `end()` in the run's `finally` is the other half, and for the same reason —
+ * see {@link ActiveFetch.end} for the two things it does together.
+ *
+ * Owns the token mechanics and the status channel; the caller keeps its own
+ * loading/error/commit side-effects. Three holders: `FetchMixin` as a member
+ * (so `cancelFetch` can reach it), `installFetch` one per installation (every
+ * other fetch in the tree runs on that skeleton), and the synteny diagonalize
+ * progress wrapper (`withDiagonalizeProgress`) directly.
+ *
+ * `report` is passed rather than read off `self`, so where the status lands is
+ * the caller's decision and not a shape this imposes. A display passes itself —
+ * its status fields are part of its own API, and one composing `FetchMixin`
+ * passes the model-wide window along with them (see `StatusReporter`).
+ * Anything with one operation to narrate and no status vocabulary of its own
+ * passes a {@link createStatusChannel}, which is one volatile instead of two
+ * fields and an action.
+ */
+export declare function createStopTokenRotation(self: IStateTreeNode, report: StatusReporter): {
+    begin(): ActiveFetch;
+    cancel: () => void;
+    dispose(): void;
+};

package/esm/util/createStopTokenRotation.js

@@ -0,0 +1,147 @@
+import { isAlive } from '@jbrowse/mobx-state-tree';
+import { observable, runInAction } from 'mobx';
+import { createStatusWindow, statusFraction, statusMessageText, } from './progress.js';
+import { createStopToken, stopStopToken } from './stopToken.js';
+export function createStatusChannel() {
+    // MobX rather than MST, so this is a value a model can hold rather than a
+    // node it has to parent. A volatile is `observable.ref`, so the fields have
+    // to be observable in their own right for a component to see them move.
+    const state = observable({
+        message: undefined,
+        fraction: undefined,
+    }, {}, { deep: false });
+    return {
+        get message() {
+            return state.message;
+        },
+        get fraction() {
+            return state.fraction;
+        },
+        setStatusMessage(status) {
+            // its own action: the rotation calls this from a status callback, which
+            // fires after an await and so outside whatever MST action started the
+            // fetch
+            runInAction(() => {
+                state.message = statusMessageText(status);
+                state.fraction = statusFraction(status);
+            });
+        },
+    };
+}
+/**
+ * Latest-wins stop-token rotation for a fetch that runs in a bare `autorun`
+ * rather than through `FetchMixin.runFetch` (which welds the same mechanics to
+ * `fetchGeneration`, so it's only for viewport-driven LGV fetches). Each
+ * `begin()` aborts the prior fetch's token and returns a fresh one plus an
+ * `isCurrent()` guard that captures this run's token — gate every post-await
+ * write on it and a superseded or torn-down fetch can never clobber fresher
+ * data. The guard is the return value, so a caller can't forget to compare a
+ * token by hand.
+ *
+ * `end()` in the run's `finally` is the other half, and for the same reason —
+ * see {@link ActiveFetch.end} for the two things it does together.
+ *
+ * Owns the token mechanics and the status channel; the caller keeps its own
+ * loading/error/commit side-effects. Three holders: `FetchMixin` as a member
+ * (so `cancelFetch` can reach it), `installFetch` one per installation (every
+ * other fetch in the tree runs on that skeleton), and the synteny diagonalize
+ * progress wrapper (`withDiagonalizeProgress`) directly.
+ *
+ * `report` is passed rather than read off `self`, so where the status lands is
+ * the caller's decision and not a shape this imposes. A display passes itself —
+ * its status fields are part of its own API, and one composing `FetchMixin`
+ * passes the model-wide window along with them (see `StatusReporter`).
+ * Anything with one operation to narrate and no status vocabulary of its own
+ * passes a {@link createStatusChannel}, which is one volatile instead of two
+ * fields and an action.
+ */
+export function createStopTokenRotation(self, report) {
+    let currentStopToken;
+    // The host's window when it has one, so a display composing `FetchMixin` has
+    // one window rather than two writing one field; our own otherwise. Lent means
+    // this fetch is one slot beside the host's others rather than a second writer
+    // (ADR-081), which is why `end()` no longer has to ask whether it owns the
+    // field.
+    const lent = report.statusWindow !== undefined;
+    const statusWindow = report.statusWindow
+        ? report.statusWindow
+        : // the one place the field is touched, so the liveness check covers a
+            // stream's statuses and the clear that ends it alike
+            createStatusWindow((status) => {
+                if (isAlive(self)) {
+                    report.setStatusMessage(status);
+                }
+            });
+    let openStream;
+    /**
+     * Stop the in-flight fetch without starting one, and retire its slot.
+     *
+     * Dropping `currentStopToken` rather than only stopping it is what closes
+     * every outstanding guard: `isCurrent` compares against this field, so one
+     * assignment makes a fetch already past its await stale, whether it is the one
+     * being cancelled or a superseded predecessor still unwinding.
+     *
+     * Retiring, not blanking — the field goes blank only if this was the last
+     * operation reporting on it (ADR-081).
+     *
+     * Named rather than reached through `this`, so a destructured `dispose` still
+     * works: `addDisposer(self, rotation.dispose)` is a shape callers reach for.
+     */
+    const cancel = () => {
+        if (currentStopToken) {
+            stopStopToken(currentStopToken);
+            currentStopToken = undefined;
+        }
+        // a fetch in flight when this is called never reaches its `finally`, and a
+        // slot nobody retires goes on voting
+        openStream?.clear();
+        openStream = undefined;
+    };
+    return {
+        begin() {
+            if (currentStopToken) {
+                stopStopToken(currentStopToken);
+            }
+            const stopToken = createStopToken();
+            currentStopToken = stopToken;
+            // `ended` is the term a completed fetch has no other way to express: the
+            // token comparison catches a SUPERSEDED one, but a fetch that simply
+            // finished still holds the current token. The stream reads it as well as
+            // the caller's commit guard, which is why both go through this closure.
+            let ended = false;
+            const isCurrent = () => !ended && stopToken === currentStopToken && isAlive(self);
+            // Opened BEFORE the superseded run reaches its `finally`, which is what
+            // keeps the label the user is looking at from blanking between the two:
+            // the run being replaced is suspended at an await and resumes a microtask
+            // from now, by which point this slot is already voting. A fetch being
+            // SUPERSEDED is the one case where the display does not stop loading, so
+            // a gap there reads as the overlay's `'Loading'` fallback (ADR-080).
+            const stream = statusWindow.open({ isCurrent });
+            openStream = stream;
+            return {
+                stopToken,
+                isCurrent,
+                statusCallback: stream.statusCallback,
+                end() {
+                    ended = true;
+                    if (openStream === stream) {
+                        openStream = undefined;
+                    }
+                    stream.clear();
+                },
+            };
+        },
+        cancel,
+        dispose() {
+            cancel();
+            // the window outlives the token: a trailing write is queued on a timer,
+            // and while the sink's `isCurrent` makes it a no-op rather than a write to
+            // a dead node, the timer itself still stands for up to a window past
+            // teardown. Only ours — resetting a lent one drops a write the host's
+            // other operations are still owed.
+            if (!lent) {
+                statusWindow.reset();
+            }
+        },
+    };
+}

package/esm/util/createSvgRasterCanvas.d.ts

@@ -0,0 +1,7 @@
+export interface SvgRasterCanvasOpts {
+    createCanvas?: (width: number, height: number) => HTMLCanvasElement;
+}
+export declare function createSvgRasterCanvas(width: number, height: number, opts: SvgRasterCanvasOpts | undefined): {
+    canvas: HTMLCanvasElement;
+    ctx: CanvasRenderingContext2D;
+};

package/esm/util/createSvgRasterCanvas.js

@@ -0,0 +1,22 @@
+// SVG export's "rasterize a layer to PNG" idiom: a 2× DPR canvas drawn into,
+// then embedded as <image xlinkHref={dataURL}/>. Used by every renderSvg.tsx
+// that has heavy fill paths (alignments pileup, wiggle bins, hic matrix, LD
+// matrix, etc.) where vector output would be unreasonably large.
+//
+// Fixed at 2× — exports go to print/file, not screen, so devicePixelRatio is
+// not the right scale factor.
+const SVG_RASTER_DPR = 2;
+export function createSvgRasterCanvas(width, height, opts) {
+    const dpr = SVG_RASTER_DPR;
+    const canvas = opts?.createCanvas
+        ? opts.createCanvas(width * dpr, height * dpr)
+        : document.createElement('canvas');
+    canvas.width = width * dpr;
+    canvas.height = height * dpr;
+    const ctx = canvas.getContext('2d');
+    if (!ctx) {
+        throw new Error('createSvgRasterCanvas: 2D context unavailable');
+    }
+    ctx.scale(dpr, dpr);
+    return { canvas, ctx };
+}

package/esm/util/crypto.d.ts

@@ -1,7 +1,31 @@
+/**
+ * AES encrypt compatible with crypto-js OpenSSL format
+ * Uses Web Crypto API when available, falls back to pure JS in non-secure contexts
+ */
 export declare function aesEncrypt(plaintext: string, password: string): Promise<string>;
+/**
+ * AES decrypt compatible with crypto-js OpenSSL format
+ * Uses Web Crypto API when available, falls back to pure JS in non-secure contexts
+ */
 export declare function aesDecrypt(ciphertext: string, password: string): Promise<string>;
+/**
+ * SHA256 hash
+ * Uses Web Crypto API when available, falls back to pure JS in non-secure contexts
+ */
 export declare function sha256(data: string): Promise<Uint8Array>;
+/**
+ * Base64 encode a Uint8Array
+ */
 export declare function toBase64(data: Uint8Array): string;
+/**
+ * URL-safe Base64 encode (for OAuth PKCE)
+ */
 export declare function toBase64Url(data: Uint8Array): string;
+/**
+ * SHA256 hash and return as Base64 (for OAuth PKCE code challenge)
+ */
 export declare function sha256Base64(data: string): Promise<string>;
+/**
+ * SHA256 hash and return as URL-safe Base64 (for OAuth PKCE code challenge)
+ */
 export declare function sha256Base64Url(data: string): Promise<string>;