@jbrowse/core 4.2.1 → 5.0.0-beta.1

package/esm/svg/svgReady.js

@@ -0,0 +1,164 @@
+import { when } from 'mobx';
+import { whenViewSettled } from '../util/whenViewSettled.js';
+// Elapsed, not idle. An idle bound would be the better instrument — a slow
+// export progresses, a stuck one does not — but there is no signal to hang it
+// on: `svgReady` is a computed that stays false for the whole fetch, so mobx
+// never re-evaluates the predicate to say work is still landing, and only one
+// of the five display families exposes `isLoading`.
+//
+// So the number carries the whole argument, and it is picked to make a false
+// failure implausible rather than merely unlikely: half an hour, against real
+// exports over remote 1000 Genomes data that finish in about ten seconds and a
+// worst measured case in low minutes. A caller that knows it is slower than
+// that passes its own bound; nothing here fails an export that is merely slow.
+const SVG_READY_TIMEOUT_MS = 1_800_000;
+/**
+ * Whether an off-screen (SVG) export can read this display's data now: the held
+ * data is current for what is on screen, or the fetch reached a terminal state.
+ *
+ * Single-sourced for the same reason as `computeDisplayPhase`: every display
+ * family expresses freshness differently — spatial coverage (per-region),
+ * viewport-snapshot compare (global), signature compare (arc / dotplot /
+ * synteny) — but the *policy* wrapping it is identical, and each of the five
+ * hand-written copies this replaced was one place to forget a terminal and hang
+ * the export, or to forget freshness and capture a stale viewport (both have
+ * shipped; see agent-docs/reference/SVG_EXPORT.md).
+ *
+ * `dataCurrent` is a **thunk**, evaluated only after the terminals are ruled
+ * out, for the same MobX reason `computeDisplayPhase`'s `loading` is: freshness
+ * typically reads the containing view's `visibleRegions` / `loadedRegions`, and
+ * the `when()` in `awaitSvgReady` shouldn't subscribe to that churn while a
+ * banner is up.
+ */
+export function computeSvgReady({ error, regionTooLarge, extraTerminal, fetchCanceled }, dataCurrent) {
+    return (!!error || regionTooLarge || extraTerminal || fetchCanceled || dataCurrent());
+}
+/**
+ * Off-screen renderers (SVG export, headless jbrowse-img) must wait until the
+ * display reaches a terminal state before reading its data. That whole policy
+ * lives in `svgReady`; this is the one shared way to await it, so renderers
+ * never re-inline `data != null || error || …`. No time bound: `svgReady` is a
+ * terminal state (data loaded, or error / too-large), so it resolves once the
+ * fetch it observes settles. If a throwing `svgReady` getter rejects the wait,
+ * that error propagates faithfully rather than being masked.
+ *
+ * It then fails the export if the terminal it settled on was the error
+ * (`throwOnExportErrors`, below, for why that is fatal), making this the exact
+ * display-level twin of `awaitViewInitialized`: both wait for `settled || error`
+ * and both refuse to continue on the error, so the postcondition of each is
+ * "there is something to draw". Folded in rather than left to the caller because
+ * `svgReady` is *true* on error, so a caller that awaits and stops there gets a
+ * display with nothing to draw and no sign of why.
+ *
+ * Every display uses this one, including the ones with nowhere to draw an error
+ * (dotplot, synteny) — a display never has to know whether it owns the surface
+ * it paints, because the thing that made that distinction matter, reporting all
+ * the failures rather than one, is `awaitSvgRenders`'s job.
+ *
+ * A standing user cancel fails the export the same way an error does, and for
+ * the same reason the error is folded in rather than left to the caller: the
+ * cancel terminal makes `svgReady` *true* over a display with nothing to draw,
+ * so a caller that awaits and stops there exports that track blank in silence.
+ * On screen the same state shows "Loading canceled / Retry", so the loud
+ * failure matches what the user is looking at.
+ */
+export async function awaitSvgReady(model, timeoutMs = SVG_READY_TIMEOUT_MS) {
+    // Only the bound is rewritten. A `svgReady` getter that throws rejects here
+    // too, and that error is the caller's answer, not a timeout.
+    await when(() => model.svgReady, { timeout: timeoutMs }).catch((e) => {
+        throw e instanceof Error && e.message === 'WHEN_TIMEOUT'
+            ? new Error(`a display never became ready to export, after ${Math.round(timeoutMs / 60_000)} minutes. ` +
+                'Every wait here ends on data, an error or a cancel, so this is ' +
+                'none of the three: a gate that cannot converge. Pass a longer ' +
+                'timeoutMs if this export really does take longer than that.')
+            : e;
+    });
+    throwOnExportErrors([
+        model.error == null && model.fetchCanceled
+            ? new Error('data loading was canceled — Retry the track, then export')
+            : model.error,
+    ]);
+}
+/**
+ * The view-level counterpart, for the wait every `renderToSvg` opens with:
+ * `whenViewSettled` in the export's own vocabulary. Why the bare
+ * `when(() => view.initialized)` it replaced could not fail — only hang — is
+ * documented there.
+ *
+ * Only a view that never initialized is fatal *here*. A track error on an
+ * initialized view is fatal too, but it is the displays' readiness waits that
+ * report it (`throwOnExportErrors`), after this one has let the export start.
+ */
+export async function awaitViewInitialized(view) {
+    if (!(await whenViewSettled(view))) {
+        // the wait only resolves on one of the two, so `error` is set here — and
+        // routing it through the shared thrower keeps one wording for "the export
+        // failed", whichever half of the export noticed
+        throwOnExportErrors([view.error]);
+    }
+}
+/**
+ * How the export answers "a track failed": by failing. A track whose data won't
+ * load has its error caught by the fetch layer and stored on the display, so the
+ * render itself still returns — with that track blank.
+ *
+ * An export is a standalone artifact, so a failed track is fatal: the dialog
+ * shows its error banner and saves nothing, and a headless caller (jbrowse-img)
+ * exits nonzero instead of writing a broken image. Drawing the error into the
+ * figure instead costs more than the red rect it leaves in the picture: on a
+ * shared surface (dotplot plot rect, synteny band) the box covers the tracks
+ * that *did* render, and a snapshot regenerated while a display is broken
+ * absorbs the stack trace as expected output — which is how a real crash sat
+ * inside two committed goldens without turning anything red.
+ *
+ * `regionTooLarge` is deliberately not routed here — see `SvgChrome`.
+ *
+ * The failures are kept on the thrown error so that nesting one `awaitSvgRenders`
+ * inside another (synteny: rows of tracks *and* levels of ribbons) still reports
+ * every leaf rather than one per group.
+ */
+export function throwOnExportErrors(errors) {
+    const failed = errors.filter(e => e != null);
+    if (failed.length > 0) {
+        throw Object.assign(new Error(`Cannot export: ${failed.join('\n')}`, { cause: failed[0] }), { exportFailures: failed });
+    }
+}
+/**
+ * The individual failures behind one rejection: the list `throwOnExportErrors`
+ * attached, or the rejection itself for anything else (a body that threw, which
+ * is a failure the same way a 404 is).
+ */
+function leafFailures(error) {
+    return error !== null &&
+        typeof error === 'object' &&
+        'exportFailures' in error &&
+        Array.isArray(error.exportFailures)
+        ? error.exportFailures
+        : [error];
+}
+async function settledOrThrow(renders) {
+    const settled = await Promise.allSettled(renders);
+    throwOnExportErrors(settled.flatMap(r => r.status === 'rejected' ? leafFailures(r.reason) : []));
+    return settled.flatMap(r => (r.status === 'fulfilled' ? [r.value] : []));
+}
+/**
+ * `Promise.all` for the renders a view fans out, differing in the one way an
+ * export needs: it fails with **every** failure instead of whichever rejected
+ * first. Exporting a session with three broken tracks should not mean finding
+ * the second one by fixing the first and exporting again. Nest it freely — an
+ * inner fan-out's failures are flattened into the outer one's report.
+ *
+ * That is also what lets every display await through the plain `awaitSvgReady`.
+ * A display on a shared surface (the dotplot's plot rect, a synteny level's
+ * band) has nowhere to draw an error and nothing complete to say alone; the
+ * alternative is for it to stay silent and let its view read the combined error
+ * back *after* the waits, which nothing enforces and every new shared-surface
+ * view has to rediscover. Here the display just throws, and being complete is
+ * the fan-out's job rather than the display's.
+ */
+export async function awaitSvgRenders(renders) {
+    // the mapped-tuple return type `Promise.all` also declares, and also can't
+    // produce from a value-level `map`. Past the throw inside, every entry is
+    // fulfilled, so the array really is that tuple.
+    return (await settledOrThrow(renders));
+}

package/esm/svg/trackNames.d.ts

@@ -0,0 +1,27 @@
+import type { AnyConfigurationModel } from '../configuration/index.ts';
+import type { NotificationSink, TrackCatalog } from '../util/index.ts';
+/**
+ * The name an export writes for a track. HTML in a config's name is stripped
+ * before it is measured or drawn, so the reserved gutter matches the glyphs.
+ *
+ * In core rather than in the LGV plugin because the skip notification below has
+ * to name tracks the same way the labels do, and the views that need to send it
+ * are not all LGV-family — a circular view depends on neither.
+ */
+export declare function svgTrackName(track: {
+    configuration: AnyConfigurationModel;
+}, session: TrackCatalog): string;
+/**
+ * Tell the user which visible tracks the export left out because their display
+ * type implements no `renderSvg`. Called once per export, after the renders —
+ * the stacked views flatten every row's `skippedTracks` into one call rather
+ * than notifying per row.
+ *
+ * Skipping is deliberate (see `SvgExportTrack.renderSvg`), so this is
+ * informational rather than an error. But it is not silent: a figure that is
+ * quietly short a track is worse than one whose author was told why, and the
+ * reader of the file has no way to tell the difference afterwards.
+ */
+export declare function notifySkippedSvgTracks(session: NotificationSink & TrackCatalog, skipped: {
+    configuration: AnyConfigurationModel;
+}[]): void;

package/esm/svg/trackNames.js

@@ -0,0 +1,31 @@
+import { coarseStripHTML } from '../util/index.js';
+import { getTrackName } from '../util/tracks.js';
+/**
+ * The name an export writes for a track. HTML in a config's name is stripped
+ * before it is measured or drawn, so the reserved gutter matches the glyphs.
+ *
+ * In core rather than in the LGV plugin because the skip notification below has
+ * to name tracks the same way the labels do, and the views that need to send it
+ * are not all LGV-family — a circular view depends on neither.
+ */
+export function svgTrackName(track, session) {
+    return coarseStripHTML(getTrackName(track.configuration, session));
+}
+/**
+ * Tell the user which visible tracks the export left out because their display
+ * type implements no `renderSvg`. Called once per export, after the renders —
+ * the stacked views flatten every row's `skippedTracks` into one call rather
+ * than notifying per row.
+ *
+ * Skipping is deliberate (see `SvgExportTrack.renderSvg`), so this is
+ * informational rather than an error. But it is not silent: a figure that is
+ * quietly short a track is worse than one whose author was told why, and the
+ * reader of the file has no way to tell the difference afterwards.
+ */
+export function notifySkippedSvgTracks(session, skipped) {
+    if (skipped.length === 0) {
+        return;
+    }
+    const names = skipped.map(t => svgTrackName(t, session)).join(', ');
+    session.notify(`Not included in the SVG: ${names}. ${skipped.length === 1 ? 'Its display type does' : 'Their display types do'} not support SVG export.`, 'info');
+}

package/esm/svg/wrapSvgExport.d.ts

@@ -0,0 +1,12 @@
+import type { ThemeOptions } from '@mui/material';
+export declare function wrapSvgExport({ theme, width, height, margin, fontFamily, Wrapper, children, }: {
+    theme: ThemeOptions | undefined;
+    width: number;
+    height: number;
+    margin?: number;
+    fontFamily?: string;
+    Wrapper?: React.FC<{
+        children: React.ReactNode;
+    }>;
+    children: React.ReactNode;
+}): string;

package/esm/svg/wrapSvgExport.js

@@ -0,0 +1,78 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { ThemeProvider } from '@mui/material';
+import { StyleThemeProvider } from '../ui/PaletteContext.js';
+import { resolveStyleTheme } from '../ui/styleTheme.js';
+import { createJBrowseTheme } from '../ui/theme.js';
+import { resetSvgClipIds } from '../util/SvgCanvas.js';
+import { renderToStaticMarkup } from '../util/renderToStaticMarkup.js';
+import { SVGExportRoot } from './SvgExport.js';
+// Coordinates computed as bp/bpPerPx land in attributes as long floats
+// (`-32.4816`) or floating-point noise (`242.23839999999998`), bloating exports
+// with sub-pixel precision no renderer needs. Round numbers inside a fixed
+// whitelist of numeric attributes, so a track label or id that happens to look
+// numeric is never a candidate for rewriting. Geometry gets 2 decimals
+// (sub-pixel); opacity keeps 3 so a faint 0.01 mark can't collapse to 0.
+const COORD_ATTRS = [
+    'x',
+    'y',
+    'x1',
+    'y1',
+    'x2',
+    'y2',
+    'cx',
+    'cy',
+    'r',
+    'rx',
+    'ry',
+    'dx',
+    'dy',
+    'width',
+    'height',
+    'd',
+    'points',
+    'transform',
+    'gradientTransform',
+    'offset',
+    'viewBox',
+    'font-size',
+    'stroke-width',
+    'stroke-dashoffset',
+    'stroke-dasharray',
+];
+const OPACITY_ATTRS = [
+    'opacity',
+    'fill-opacity',
+    'stroke-opacity',
+    'stop-opacity',
+    'flood-opacity',
+];
+function makeRounder(attrs, digits) {
+    const re = new RegExp(`\\b(${attrs.join('|')})="([^"]*)"`, 'g');
+    return (svg) => svg.replaceAll(re, (_, name, value) => {
+        const rounded = value.replaceAll(/-?\d+\.\d{3,}(?:e-?\d+)?/gi, n => String(Number.parseFloat(Number(n).toFixed(digits))));
+        return `${name}="${rounded}"`;
+    });
+}
+const roundCoords = makeRounder(COORD_ATTRS, 2);
+const roundOpacity = makeRounder(OPACITY_ATTRS, 3);
+function roundSvgNumbers(svg) {
+    return roundOpacity(roundCoords(svg));
+}
+// The identical tail every view's `renderToSvg` ends in: resolve the export
+// theme into a provider, apply the caller-supplied Wrapper, wrap the content in
+// the root <svg>, and serialize to a markup string. Callers keep their own
+// layout math and children — only this boilerplate lives here.
+export function wrapSvgExport({ theme, width, height, margin, fontFamily, Wrapper = ({ children }) => children, children, }) {
+    // One document, one clip-id numbering run. The counter SvgCanvas draws from is
+    // document-global because SVG ids are, so left alone it also spans documents
+    // and numbers each export from wherever the last one stopped — see
+    // resetSvgClipIds. This is the only place that can reset it: the render below
+    // is synchronous, so it is the one moment a whole document's ids are minted
+    // with no other export able to interleave.
+    resetSvgClipIds();
+    // Both providers, from the same options — the export renders outside every
+    // React tree the app mounted, so a `makeStyles` component here would
+    // otherwise style itself from the *default* style theme and quietly ignore
+    // the theme the user picked in the export dialog.
+    return roundSvgNumbers(renderToStaticMarkup(_jsx(ThemeProvider, { theme: createJBrowseTheme(theme), children: _jsx(StyleThemeProvider, { theme: resolveStyleTheme({ configTheme: theme }), children: _jsx(Wrapper, { children: _jsx(SVGExportRoot, { width: width, height: height, margin: margin, fontFamily: fontFamily, children: children }) }) }) })));
+}

package/esm/ui/ActionLink.d.ts

@@ -0,0 +1,7 @@
+/** A Link that acts as a button — no real navigation, just calls onClick. */
+export default function ActionLink({ onClick, children, className, title, }: {
+    onClick: () => void;
+    children: React.ReactNode;
+    className?: string;
+    title?: string;
+}): import("react").JSX.Element;

package/esm/ui/ActionLink.js

@@ -0,0 +1,9 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { Link } from '@mui/material';
+/** A Link that acts as a button — no real navigation, just calls onClick. */
+export default function ActionLink({ onClick, children, className, title, }) {
+    return (_jsx(Link, { href: "#", className: className, title: title, onClick: (e) => {
+            e.preventDefault();
+            onClick();
+        }, children: children }));
+}

package/esm/ui/AddCustomPluginDialog.d.ts

@@ -0,0 +1,14 @@
+import type { PluginDefinition } from '../pluginDefinitions.ts';
+/**
+ * The "add a plugin by url" form, shared by every place a plugin can be
+ * installed from outside the store — the in-session plugin store widget and
+ * Desktop's global plugins dialog — so both mint the same definition shapes
+ * from the same fields.
+ *
+ * `onAdd` returns false to reject the definition and keep the dialog open (the
+ * plugin store rejects a name already installed).
+ */
+export default function AddCustomPluginDialog({ onClose, onAdd, }: {
+    onClose: () => void;
+    onAdd: (definition: PluginDefinition) => boolean;
+}): import("react").JSX.Element;

package/esm/ui/AddCustomPluginDialog.js

@@ -0,0 +1,61 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { useState } from 'react';
+import ExpandMoreIcon from '@mui/icons-material/ExpandMore';
+import { Collapse, DialogContentText, IconButton, TextField, } from '@mui/material';
+import { cx, makeStyles } from '../util/tss-react/index.js';
+import SubmitDialog from './SubmitDialog.js';
+const useStyles = makeStyles()({
+    dialogContent: {
+        display: 'flex',
+        flexDirection: 'column',
+    },
+    expand: {
+        transform: 'rotate(0deg)',
+        marginLeft: 'auto',
+        // Material's `shortest` duration and default easing, spelled out
+        transition: 'transform 150ms cubic-bezier(0.4, 0, 0.2, 1) 0ms',
+    },
+    expandOpen: {
+        transform: 'rotate(180deg)',
+    },
+});
+/**
+ * The "add a plugin by url" form, shared by every place a plugin can be
+ * installed from outside the store — the in-session plugin store widget and
+ * Desktop's global plugins dialog — so both mint the same definition shapes
+ * from the same fields.
+ *
+ * `onAdd` returns false to reject the definition and keep the dialog open (the
+ * plugin store rejects a name already installed).
+ */
+export default function AddCustomPluginDialog({ onClose, onAdd, }) {
+    const { classes } = useStyles();
+    const [umdPluginName, setUMDPluginName] = useState('');
+    const [umdPluginUrl, setUMDPluginUrl] = useState('');
+    const [esmPluginUrl, setESMPluginUrl] = useState('');
+    const [cjsPluginUrl, setCJSPluginUrl] = useState('');
+    const [advancedOptionsOpen, setAdvancedOptionsOpen] = useState(false);
+    const ready = Boolean((umdPluginName && umdPluginUrl) || esmPluginUrl || cjsPluginUrl);
+    return (_jsx(SubmitDialog, { open: true, maxWidth: "sm", fullWidth: true, title: "Add custom plugin", submitDisabled: !ready, onCancel: onClose, onSubmit: () => {
+            const definition = umdPluginName && umdPluginUrl
+                ? { name: umdPluginName, umdUrl: umdPluginUrl }
+                : esmPluginUrl
+                    ? { esmUrl: esmPluginUrl }
+                    : { cjsUrl: cjsPluginUrl };
+            if (onAdd(definition)) {
+                onClose();
+            }
+        }, children: _jsxs("div", { className: classes.dialogContent, children: [_jsx(DialogContentText, { children: "Enter the name of the plugin and its URL. The name should match what is defined in the plugin's build." }), _jsx(TextField, { label: "Plugin name", variant: "outlined", fullWidth: true, margin: "dense", value: umdPluginName, onChange: event => {
+                        setUMDPluginName(event.target.value);
+                    } }), _jsx(TextField, { label: "Plugin URL", variant: "outlined", fullWidth: true, margin: "dense", value: umdPluginUrl, onChange: event => {
+                        setUMDPluginUrl(event.target.value);
+                    } }), _jsxs(DialogContentText, { onClick: () => {
+                        setAdvancedOptionsOpen(!advancedOptionsOpen);
+                    }, children: [_jsx(IconButton, { className: cx(classes.expand, {
+                                [classes.expandOpen]: advancedOptionsOpen,
+                            }), "aria-expanded": advancedOptionsOpen, "aria-label": "show more", children: _jsx(ExpandMoreIcon, {}) }), "Advanced options"] }), _jsx(Collapse, { in: advancedOptionsOpen, children: _jsxs("div", { className: classes.dialogContent, children: [_jsx(DialogContentText, { children: "The above fields assume that the plugin is built in UMD format. If your plugin is in another format, or you have additional builds you want to add (such as a CJS build for using NodeJS APIs in desktop), you can enter the URLs for those builds below." }), _jsx(TextField, { label: "ESM build URL", variant: "outlined", fullWidth: true, margin: "dense", value: esmPluginUrl, onChange: event => {
+                                    setESMPluginUrl(event.target.value);
+                                } }), _jsx(TextField, { label: "CJS build URL", variant: "outlined", fullWidth: true, margin: "dense", value: cjsPluginUrl, onChange: event => {
+                                    setCJSPluginUrl(event.target.value);
+                                } })] }) })] }) }));
+}

package/esm/ui/AddGenomePane.d.ts

@@ -0,0 +1,8 @@
+import type { FormState } from '../util/assemblyConfigUtils.ts';
+declare const AddGenomePane: ({ form, setForm, loading, onStageAnother, }: {
+    form: FormState;
+    setForm: (update: (prev: FormState) => FormState) => void;
+    loading?: string;
+    onStageAnother?: () => Promise<boolean>;
+}) => import("react").JSX.Element;
+export default AddGenomePane;