@jbrowse/plugin-linear-genome-view 4.3.0 → 5.0.0-beta.2

package/esm/LinearGenomeView/svgcomponents/renderViewTracks.js

@@ -0,0 +1,66 @@
+import { awaitSvgRenders } from '@jbrowse/core/svg/svgReady';
+import { max } from '@jbrowse/core/util';
+import { totalHeight } from './util.js';
+/**
+ * One view's worth of exported track bodies: which tracks are in, their
+ * rendered SVG, and how tall the stack ends up.
+ *
+ * It exists to own the two orderings that each of the three view exports got
+ * wrong at least once, because neither is visible at a call site that merely
+ * lists the same statements in some order:
+ *
+ * - `legendWidth` is measured **before** the awaits, because it is an input to
+ *   them: a display draws its legend beside its body or floating over it
+ *   depending on whether the container reserved room. That is why
+ *   `svgLegendWidth` is specified as a function of the *settings* and not of
+ *   the loaded data — see LinearHicDisplay's implementation.
+ * - `tracksHeight` is measured **after** them. A display whose height follows
+ *   its data (grow mode; `LinearMultiRowFeatureDisplay` is `nrow *
+ *   effectiveRowHeight`) only reaches its final height once `renderSvg`'s
+ *   readiness wait resolves, and `SVGTracks` re-reads `displays[0].height`
+ *   later still. Measuring up front sized the canvas for the pre-fetch height
+ *   and the taller bodies ran off the bottom of the export — and in the
+ *   breakpoint-split export it also desynced the overlay anchors, resolved
+ *   after, from the view tops, which weren't.
+ *
+ * The minimized filter and the track order are here for the same reason: the
+ * reserved height, the rendered bodies, the label gutter and (breakpoint-split)
+ * the ribbon anchors must all be derived from one list, and pinned tracks are
+ * drawn at the top of a view on screen.
+ */
+export async function renderViewTracks({ view, opts, theme, textHeight, trackLabels, reserveLegendWidth = false, }) {
+    // Partitioned before anything is measured, so a skipped track reserves no
+    // height and takes no place in the label gutter — the alternative is a figure
+    // with a labelled empty band where the track would have been. One pass, so
+    // the test for "can this render" is written once and the two lists cannot
+    // disagree about a track.
+    const tracks = [];
+    const skippedTracks = [];
+    for (const track of [...view.pinnedTracks, ...view.unpinnedTracks]) {
+        if (!track.minimized) {
+            ;
+            (track.displays[0]?.renderSvg ? tracks : skippedTracks).push(track);
+        }
+    }
+    const legendWidth = reserveLegendWidth
+        ? max(tracks.map(track => track.displays[0].svgLegendWidth?.() ?? 0), 0)
+        : 0;
+    // `awaitSvgRenders` over `Promise.all`: a track whose data won't load fails
+    // the export, and a view with three broken tracks should say so once rather
+    // than name whichever rejected first
+    const displayResults = await awaitSvgRenders(tracks.map(async (track) => ({
+        track,
+        result: await track.displays[0].renderSvg({
+            ...opts,
+            theme,
+            legendWidth,
+        }),
+    })));
+    return {
+        tracks,
+        displayResults,
+        tracksHeight: totalHeight(tracks, textHeight, trackLabels),
+        legendWidth,
+        skippedTracks,
+    };
+}

package/esm/LinearGenomeView/svgcomponents/useViewSvgFigure.d.ts

@@ -0,0 +1,70 @@
+import type { LinearGenomeViewModel } from '../index.ts';
+import type { TrackLabelMode } from '../types.ts';
+import type React from 'react';
+/** What a figure's shape is, where JBrowse has no opinion of its own. */
+export interface ViewSvgFigureOptions {
+    fontSize?: number;
+    rulerHeight?: number;
+    trackLabels?: TrackLabelMode;
+    showGridlines?: boolean;
+    /** the capped bar labelled with the span, above the ruler */
+    showScalebar?: boolean;
+    /**
+     * Paint each display's heavy layer to a canvas and embed a PNG instead of
+     * emitting vector elements. The point of an inline figure is usually the
+     * opposite, but a hundred-thousand-read pileup is a lot of DOM.
+     */
+    rasterizeLayers?: boolean;
+    /** gutter on each side, for content drawn outside the genome area */
+    margin?: number;
+    /** a named theme, as the export dialog's picker passes */
+    themeName?: string;
+}
+export interface ViewSvgFigureResult {
+    /**
+     * The figure, ready to render. Frozen against the snapshot it was built from
+     * (see the note above), so re-rendering the component that holds it cannot
+     * make its chrome disagree with its track bodies.
+     */
+    figure: React.ReactNode;
+    /**
+     * Dimensions of the figure, for a host reserving its space — of the *last*
+     * one drawn while a redraw is in flight, since a reservation that went
+     * undefined between figures would collapse the box and walk the page.
+     */
+    width: number | undefined;
+    height: number | undefined;
+    /** the locus it is a picture of, for a caption */
+    locstring: string | undefined;
+    /**
+     * Names of visible tracks left out, because their display type implements no
+     * `renderSvg`. Not an error — a third-party display that has skipped a
+     * substantial extra implementation should cost its own track a place in the
+     * figure rather than cost the whole export — but not nothing either, since a
+     * figure quietly one track short is indistinguishable afterwards from a figure
+     * of a view that had one fewer. Say it somewhere.
+     */
+    skipped: string[];
+    error: unknown;
+    isLoading: boolean;
+}
+/**
+ * A live SVG figure of a linear genome view, redrawn as the view settles
+ * somewhere new.
+ *
+ * ```tsx
+ * const { figure, isLoading, skipped } = useViewSvgFigure(view)
+ * return <div>{figure}</div>
+ * ```
+ *
+ * The data is the display's own — whatever it has already fetched for the
+ * screen — so a figure costs no requests.
+ *
+ * `useFetch` under it, which is what discards a redraw that lands after the pan
+ * that overtook it. Every change of key clears its data, a pan as much as a
+ * theme switch, so `figure` goes undefined for as long as the next one takes to
+ * build — which is what `width`/`height` holding the last figure's box is for:
+ * the reservation keeps its size while the content is away, instead of
+ * collapsing and walking the page.
+ */
+export declare function useViewSvgFigure(view: LinearGenomeViewModel, { fontSize, rulerHeight, trackLabels, showGridlines, showScalebar, rasterizeLayers, margin, themeName, }?: ViewSvgFigureOptions): ViewSvgFigureResult;

package/esm/LinearGenomeView/svgcomponents/useViewSvgFigure.js

@@ -0,0 +1,263 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { memo, useCallback, useEffect, useRef, useSyncExternalStore, } from 'react';
+import { exportMargin } from '@jbrowse/core/svg/constants';
+import { svgTrackName } from '@jbrowse/core/svg/trackNames';
+import { StyleThemeProvider } from '@jbrowse/core/ui/PaletteContext';
+import { resolveStyleTheme } from '@jbrowse/core/ui/styleTheme';
+import { createJBrowseTheme } from '@jbrowse/core/ui/theme';
+import { getSession } from '@jbrowse/core/util';
+import { useFetch } from '@jbrowse/core/util/useFetch';
+import { isAlive } from '@jbrowse/mobx-state-tree';
+import { ThemeProvider } from '@mui/material';
+import { reaction } from 'mobx';
+import SVGRowHeader from './SVGRowHeader.js';
+import SVGView from './SVGView.js';
+import { useFrozenFigureContract, useOneFigurePerView, } from './figureContract.js';
+import { renderViewTracks } from './renderViewTracks.js';
+import { defaultTextHeight, getRowHeaderLayout, trackLabelLeftOffset, } from './util.js';
+/**
+ * One figure: every visible track rendered to SVG elements, and the geometry
+ * that lays them out.
+ *
+ * `renderViewTracks` owns the two orderings this cannot state for itself — the
+ * legend gutter measured before the renders (a display draws its key beside the
+ * plot or floating over it depending on whether the container reserved room),
+ * the stack height after them (a display whose height follows its data only
+ * reaches its final height once its readiness wait resolves). Everything read
+ * below is read after the awaits for the same reason.
+ */
+async function renderFigure(view, opts) {
+    const { fontSize, rulerHeight, trackLabels, rasterizeLayers, showScalebar } = opts;
+    const session = getSession(view);
+    const theme = session.getActiveThemeOptions?.(opts.themeName);
+    const textHeight = defaultTextHeight(fontSize);
+    const { tracks, displayResults, tracksHeight, legendWidth, skippedTracks } = await renderViewTracks({
+        view,
+        opts: {
+            fontSize,
+            trackLabels,
+            rasterizeLayers,
+            themeName: opts.themeName,
+        },
+        theme,
+        textHeight,
+        trackLabels,
+        // an inline figure has room to give: a legend sits beside the plot rather
+        // than over it
+        reserveLegendWidth: true,
+    });
+    // the room the row header needs *above* its own origin — it draws the assembly
+    // name and the scalebar at negative y, so the caller reserves the band and
+    // translates the view down into it
+    const { bandHeight } = getRowHeaderLayout({ fontSize, showScalebar });
+    const trackLabelOffset = trackLabelLeftOffset({
+        tracks,
+        trackLabels,
+        fontSize,
+        session,
+    });
+    return {
+        ...opts,
+        displayResults,
+        theme,
+        width: view.width + opts.margin * 2 + legendWidth + trackLabelOffset,
+        height: bandHeight + rulerHeight + tracksHeight + opts.margin,
+        bandHeight,
+        tracksHeight,
+        legendWidth,
+        trackLabelOffset,
+        textHeight,
+        locstring: view.visibleLocStrings,
+        skipped: skippedTracks.map(track => svgTrackName(track, session)),
+    };
+}
+/**
+ * The figure, frozen.
+ *
+ * `memo` is what keeps the live half of the drawing (the ruler, the scalebar,
+ * the seams, all of which re-read the model) from advancing past the frozen half
+ * while a redraw is in flight — the snapshot is the only thing that may move it.
+ *
+ * **It looks redundant in this repo and is not, and the difference is the
+ * build.** `babel.config.cjs` runs React Compiler over every component here, so
+ * a re-render of this one with an unchanged `snapshot` reuses its whole memoized
+ * element tree and the chrome never re-runs — which is why taking the `memo` out
+ * fails no test in this repo. What ships is `build:esm`, plain `tsc` with no
+ * compiler pass, so a consumer's app re-renders this component on every parent
+ * render. Where it matters, this line is the only thing holding the two halves
+ * together.
+ *
+ * Both providers, as `wrapSvgExport` mounts for the file path, and for the same
+ * reason: the chrome takes its colors from the Material UI theme and a
+ * `makeStyles` component would take its own from the style theme, so a figure
+ * mounted in a host that installs neither would otherwise draw itself in
+ * JBrowse's *default light* theme whatever the session is set to.
+ *
+ * No background rect, unlike a file — that has nothing behind it, and a figure
+ * in a page has the page. No `resetSvgClipIds` either, and that is the opposite
+ * decision from the file path on purpose: the counter is document-global, so
+ * resetting it here would renumber ids that a figure already on the page is
+ * pointing at. Letting it run is what makes several live figures unique.
+ */
+const FrozenSvgFigure = memo(function FrozenSvgFigure({ view, snapshot, }) {
+    const { width, height, margin, theme } = snapshot;
+    // it watches for the one thing this component cannot enforce: an observer
+    // INSIDE the tree, which the memo above is not between
+    const ref = useRef(null);
+    useFrozenFigureContract(ref, snapshot);
+    return (_jsx(ThemeProvider, { theme: createJBrowseTheme(theme), children: _jsx(StyleThemeProvider, { theme: resolveStyleTheme({ configTheme: theme }), children: _jsx("svg", { ref: ref, width: width, height: height, viewBox: `0 0 ${width} ${height}`, 
+                // It is a vector, so a narrower container scales it rather than
+                // clipping it; the height attribute stays, so a box reserved for it
+                // does not change size when that happens. Deliberately not a prop:
+                // anything passed per-render would have to reach past the memo above,
+                // which is the one thing holding the figure's two halves together. A
+                // host that wants other sizing wraps this in a box of its own.
+                style: { display: 'block', maxWidth: '100%' }, children: _jsx("g", { transform: `translate(${margin} ${snapshot.bandHeight})`, children: _jsx(SVGView, { view: view, displayResults: snapshot.displayResults, header: _jsx(SVGRowHeader, { view: view, fontSize: snapshot.fontSize, rulerHeight: snapshot.rulerHeight, showScalebar: snapshot.showScalebar }), fontSize: snapshot.fontSize, textHeight: snapshot.textHeight, trackLabels: snapshot.trackLabels, trackLabelOffset: snapshot.trackLabelOffset, 
+                        // the row header is exactly the ruler, so the bodies start at its
+                        // height
+                        contentTop: snapshot.rulerHeight, tracksHeight: snapshot.tracksHeight, showGridlines: snapshot.showGridlines, 
+                        // the left gutter the per-track clip may bleed into, so content
+                        // drawn left of zero — a wiggle's y-axis — survives
+                        leftBuffer: snapshot.margin, legendWidth: snapshot.legendWidth }) }) }) }) }));
+});
+/**
+ * What "the figure is out of date" means, as a string.
+ *
+ * The settled frame rather than the live one: `coarseVisibleLocStrings` and
+ * `coarseBpPerPx` are a 500ms-delayed copy of the view's geometry — the same
+ * signal the wiggle and alignments displays refetch on — so a figure redraws
+ * when the reader stops rather than once a frame. A redraw walks every visible
+ * feature and builds a few thousand DOM nodes; that is the trade an inline
+ * figure makes, and it is why the canvas rendering still exists.
+ *
+ * The rest is everything else a figure is a picture of, and each entry is here
+ * because leaving it out is silent: **the tracks**, since `ready` answers a
+ * question about regions and is true before a track is instantiated (the first
+ * figure then draws a header over nothing, and nothing else ever changes to
+ * correct it); **their heights and minimized flags**, since the geometry is
+ * derived from them; **the width**, since a resize can widen the canvas without
+ * moving the locus; **the theme**, since each display bakes colors into its own
+ * bodies, so a figure from the other mode is not stale but unreadable; and **the
+ * highlight bands**, which are drawn in the figure and are the one thing in it a
+ * reader adds without navigating anywhere.
+ *
+ * A plugin's own overlay (grid-bookmark's bookmarks, through
+ * `LinearGenomeView-HighlightSVGComponent`) is state this cannot see, so a
+ * bookmark added under a drawn figure shows up at its next redraw rather than at
+ * once. Subscribing from inside the figure is the thing that must not happen —
+ * see the note at the top of the file.
+ */
+function figureKey(view, themeName) {
+    // A closed view is not an error, it is a host doing an ordinary thing in an
+    // order React cannot help with: the MST node dies on the write, and this
+    // reaction re-runs against the corpse before the host's own render takes the
+    // figure down. Every read below is then a dead-node read — `track.displays[0]`
+    // warns and `track.configuration` comes back undefined, so the key used to
+    // throw a TypeError inside the reaction, where MobX swallows it. No key means
+    // no figure, which is what a host that closed the view wanted anyway.
+    //
+    // `view.width` throws by design before the view has been measured, and
+    // `ready` is the gate that says it has been — and that there are regions to
+    // draw, which is the second async step `initialized` does not cover
+    if (!isAlive(view) || !view.ready) {
+        return '';
+    }
+    const session = getSession(view);
+    return JSON.stringify([
+        view.coarseVisibleLocStrings,
+        view.coarseBpPerPx,
+        view.width,
+        view.tracks.map(track => [
+            track.configuration.trackId,
+            track.minimized,
+            track.displays[0]?.height,
+        ]),
+        session.getActiveThemeOptions?.(themeName),
+        session.highlightsVisible ? view.highlight : false,
+        view.labelsVisible,
+    ]);
+}
+/**
+ * Subscribe to that key from outside MobX.
+ *
+ * `useSyncExternalStore` rather than reading the model in the caller's render,
+ * so this works whether or not the calling component is an `observer` — a hook
+ * that silently stops redrawing for hosts who did not wrap their component is
+ * not a publishable contract. `reaction` rather than `autorun` for once, and for
+ * the reason the usual rule is the other way round: `getSnapshot` already
+ * supplies the current value, so the subscription only has to report changes.
+ */
+function useFigureKey(view, themeName) {
+    return useSyncExternalStore(useCallback((onChange) => reaction(() => figureKey(view, themeName), onChange), [view, themeName]), () => figureKey(view, themeName), () => '');
+}
+/**
+ * A live SVG figure of a linear genome view, redrawn as the view settles
+ * somewhere new.
+ *
+ * ```tsx
+ * const { figure, isLoading, skipped } = useViewSvgFigure(view)
+ * return <div>{figure}</div>
+ * ```
+ *
+ * The data is the display's own — whatever it has already fetched for the
+ * screen — so a figure costs no requests.
+ *
+ * `useFetch` under it, which is what discards a redraw that lands after the pan
+ * that overtook it. Every change of key clears its data, a pan as much as a
+ * theme switch, so `figure` goes undefined for as long as the next one takes to
+ * build — which is what `width`/`height` holding the last figure's box is for:
+ * the reservation keeps its size while the content is away, instead of
+ * collapsing and walking the page.
+ */
+export function useViewSvgFigure(view, { fontSize = 12, rulerHeight = 30, trackLabels = 'offset', showGridlines = true, showScalebar = true, rasterizeLayers = false, margin = exportMargin, themeName, } = {}) {
+    const key = useFigureKey(view, themeName);
+    useOneFigurePerView(view);
+    const { data: snapshot, error, isLoading, } = useFetch(
+    // Every option is in the key by value, so an inline options object costs
+    // nothing and a changed option redraws. A null key is `useFetch`'s own "not
+    // yet", which is what an unready view reports.
+    key
+        ? [
+            'lgv-svg-figure',
+            key,
+            JSON.stringify([
+                fontSize,
+                rulerHeight,
+                trackLabels,
+                showGridlines,
+                showScalebar,
+                rasterizeLayers,
+                margin,
+            ]),
+        ]
+        : null, () => renderFigure(view, {
+        fontSize,
+        rulerHeight,
+        trackLabels,
+        showGridlines,
+        showScalebar,
+        rasterizeLayers,
+        margin,
+        themeName,
+    }));
+    // Written in an effect and read during render, which is the order that makes
+    // it work: a key change clears `data` on the render where the ref still holds
+    // the previous commit's size, so the host's box keeps the height it had rather
+    // than collapsing to nothing while the next figure draws.
+    const lastSize = useRef(undefined);
+    useEffect(() => {
+        if (snapshot) {
+            lastSize.current = { width: snapshot.width, height: snapshot.height };
+        }
+    }, [snapshot]);
+    const size = snapshot ?? lastSize.current;
+    return {
+        figure: snapshot ? (_jsx(FrozenSvgFigure, { view: view, snapshot: snapshot })) : undefined,
+        width: size?.width,
+        height: size?.height,
+        locstring: snapshot?.locstring,
+        skipped: snapshot?.skipped ?? [],
+        error,
+        isLoading,
+    };
+}

package/esm/LinearGenomeView/svgcomponents/util.d.ts

@@ -1,8 +1,95 @@
-interface Display {
-    height: number;
+import type { TrackLabelMode } from '../types.ts';
+import type { AnyConfigurationModel } from '@jbrowse/core/configuration';
+import type { TrackCatalog } from '@jbrowse/core/util';
+import type { ReactNode } from 'react';
+interface TrackHeights {
+    displays: {
+        height: number;
+    }[];
 }
-interface Track {
-    displays: Display[];
+export interface SvgDisplayResult {
+    track: {
+        configuration: AnyConfigurationModel;
+        displays: {
+            height: number;
+        }[];
+    };
+    result: ReactNode;
 }
-export declare function totalHeight(tracks: Track[], textHeight: number, trackLabels: string): number;
+export declare const trackSpacing = 2;
+export declare function gridlineTickXs(model: {
+    staticBlocksTranslateX: number;
+    gridlineTicks: {
+        major: boolean;
+        x: number;
+    }[];
+}): {
+    dx: number;
+    major: number[];
+    minor: number[];
+};
+export declare function vlinePath(xs: number[], y1: number, y2: number): string;
+export declare function labelInkHeight(fontSize: number): number;
+/**
+ * Baseline y for a label whose ink box should start at `topY` — roughly what
+ * `dominantBaseline="hanging"` asks the renderer for, but resolved here.
+ *
+ * Not a renderer-compatibility workaround (`dominant-baseline` is well
+ * supported, and SvgCanvas emits it on every feature label it writes). The
+ * point is that this file already *models* the ink box, in LABEL_INK_EM /
+ * LABEL_DESCENT_EM, and reserves vertical space from that model —
+ * `getHeaderLayout` budgets `labelInkHeight(fontSize)` for the scalebar's bp
+ * label, `defaultTextHeight` for an offset track label. A label placed with
+ * `hanging` is instead positioned by the renderer's own notion of the font's
+ * ascent, so the space reserved and the space used come from two different
+ * models that merely happen to agree closely at the sizes we ship. Resolving
+ * the baseline from the same constants makes them one model, which is what lets
+ * util.test.ts check placement against reservation at all.
+ */
+export declare function labelBaselineFromTop(topY: number, fontSize: number): number;
+export declare function defaultTextHeight(fontSize: number): number;
+export declare function offsetLabelBaselineY(textHeight: number, fontSize: number): number;
+export declare function insetLabelBaselineY(fontSize: number): number;
+export declare function getRowHeaderLayout({ fontSize, showScalebar, }: {
+    fontSize: number;
+    showScalebar: boolean;
+}): {
+    scalebarLineY: number | undefined;
+    assemblyLabelBaselineY: number;
+    bandHeight: number;
+};
+export declare function getHeaderLayout({ fontSize, showCytobands, rulerHeight, }: {
+    fontSize: number;
+    showCytobands: boolean;
+    rulerHeight: number;
+}): {
+    assemblyLabelBaselineY: number;
+    cytobandTop: number;
+    scalebarLineY: number;
+    rulerTop: number;
+    tracksTop: number;
+};
+export declare const RULER_MAJOR_TICK = 5;
+export declare const RULER_MINOR_TICK = 3;
+export declare const RULER_TICK_FONT_SIZE = 11;
+export declare function getRulerLayout(rulerHeight: number): {
+    tickTopY: number;
+    numbersBaselineY: number;
+};
+export declare const refNameLabelBoxHeight: number;
+export declare const refNameLabelBaselineY: number;
+export declare function labelOffset(trackLabels: TrackLabelMode, textHeight: number): number;
+export declare const TRACK_LABEL_GAP = 40;
+export declare function trackLabelLeftOffset({ tracks, trackLabels, fontSize, fontFamily, session, }: {
+    tracks: {
+        configuration: AnyConfigurationModel;
+    }[];
+    trackLabels: TrackLabelMode;
+    fontSize: number;
+    fontFamily?: string;
+    session: TrackCatalog;
+}): number;
+export declare function trackBoxHeight(track: TrackHeights, textOffset: number): number;
+export declare function trackBoxOffsets(tracks: TrackHeights[], textOffset: number): number[];
+export declare function totalHeight(tracks: TrackHeights[], textHeight: number, trackLabels: TrackLabelMode): number;
 export {};