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

package/esm/LinearGenomeView/model.js

@@ -8,9 +8,11 @@ import { wholeBaseRegions } from '@jbrowse/core/util/blockTypes';
 import calculateDynamicBlocks from '@jbrowse/core/util/calculateDynamicBlocks';
 import calculateStaticBlocks from '@jbrowse/core/util/calculateStaticBlocks';
 import { tickLabelsWorthDrawing } from '@jbrowse/core/util/tickLabels';
-import { hideTrackGeneric, showTrackGeneric, toggleTrackGeneric, } from '@jbrowse/core/util/tracks';
+import { hideTrackGeneric, launchToggleTrackGeneric, launchTrackGeneric, showTrackGeneric, toggleTrackGeneric, } from '@jbrowse/core/util/tracks';
 import { ElementId } from '@jbrowse/core/util/types/mst';
-import { computeViewStatus } from '@jbrowse/core/util/viewStatus';
+import { assemblyErrorMessage, computeViewStatus, } from '@jbrowse/core/util/viewStatus';
+import { pendingLaunch, withLaunchInput, } from '@jbrowse/core/util/withLaunchInput';
+import { contentRightEdgePx } from '@jbrowse/display-kit/regionHost';
 import { cast, getParent, hasParent, isAlive, types, } from '@jbrowse/mobx-state-tree';
 import { when } from 'mobx';
 import { handleSelectedRegion } from '../searchUtils.js';
@@ -19,11 +21,16 @@ import { shouldSwapTracks } from './components/util.js';
 import { HEADER_BAR_HEIGHT, HEADER_OVERVIEW_HEIGHT, MIN_BP_PER_PX, MINIMIZED_TRACK_HEIGHT, RESIZE_HANDLE_HEIGHT, SCALE_BAR_HEIGHT, SHOW_ALL_REGIONS_FILL, TRACK_OUTLINE_BORDER, TRACK_TOP_GAP, } from './consts.js';
 import { planFlight } from './flyTo.js';
 import { setupKeyboardHandler } from './keyboardHandler.js';
+import { lgvLaunchKeys } from './launchKeys.js';
 import { buildMenuItems, buildRubberBandMenuItems, buildRubberbandClickMenuItems, } from './menuItems.js';
 import { sharedScaleContainerOf } from './sharedScaleContainer.js';
 import { calculateVisibleLocStrings, cytobandLabelGutterWidth, expandRegion, fitAllRegionsWindow, generateLocations, getScalebarRefNameLabels, regionsOrientation, groupContiguousBlocks, labelFitsInBlock, makeBlockTicks, runRefNameLabelPx, tickLabelWidth, } from './util.js';
 // lazies
 const SearchResultsDialog = lazy(() => import('./components/SearchResultsDialog.js'));
+// The one array `paddingSpans` returns when a view has nothing to mask, so that
+// computed's value repeats by identity. Frozen because every consumer maps over
+// it and a caller that sorted in place would do so for the whole session.
+const NO_PADDING_SPANS = Object.freeze([]);
 /**
  * Calculate the offsetPx needed to center content within a viewport.
  * Returns a negative offset when content is smaller than viewport (padding on left).
@@ -141,30 +148,28 @@ function isTrackSelectorVisible(self) {
  * #category view
  *
  * #example
- * A `LinearGenomeView` is what you hand-author under `defaultSession.views`. The
- * `init` shorthand fills in `displayedRegions`/`bpPerPx`/`offsetPx` for you:
+ * A `LinearGenomeView` is what you hand-author under `defaultSession.views`, and
+ * every setting goes directly on the view object. `assembly`/`loc` fill in
+ * `displayedRegions`/`bpPerPx`/`offsetPx` for you:
  * ```js
  * defaultSession: {
  *   name: 'My session',
  *   views: [
  *     {
  *       type: 'LinearGenomeView',
- *       // plain persisted props sit alongside init, not inside it
  *       colorByCDS: true,
- *       init: {
- *         assembly: 'hg38',
- *         loc: 'chr1:1,000,000-1,100,000',
- *         tracks: ['genes', 'alignments'],
- *       },
+ *       assembly: 'hg38',
+ *       loc: 'chr1:1,000,000-1,100,000',
+ *       tracks: ['genes', 'alignments'],
  *     },
  *   ],
  * }
  * ```
- * `init` holds only keys that need on-attach resolution — also `tracklist`,
- * `nav`, `highlight` (see the `init` property below). Plain view props like
- * `colorByCDS`, `showAminoAcids`, `showCenterLine`, `trackLabels`,
- * `showHighlightChips` are set
- * directly on the view (MST restores them natively).
+ * `assembly`, `loc`, `tracks`, `tracklist`, `nav` and `highlight` need
+ * on-attach resolution and are captured into the `launch` property below;
+ * `colorByCDS`, `showAminoAcids`, `showCenterLine`, `trackLabels` and
+ * `showHighlightChips` are plain view props MST restores natively. Both are
+ * written the same way.
  * At runtime the same model is driven imperatively — every property and action
  * below is reachable on `viewState.session.views[0]`:
  * ```js
@@ -175,7 +180,7 @@ function isTrackSelectorVisible(self) {
  * ```
  */
 export function stateModelFactory(pluginManager) {
-    return types
+    const model = types
         .compose('LinearGenomeView', BaseViewModel, HighlightsMixin(), types.model({
         /**
          * #property
@@ -321,20 +326,14 @@ export function stateModelFactory(pluginManager) {
         scalebarOnly: types.stripDefault(types.boolean, false),
         /**
          * #property
-         * transient declarative launch spec: assembly + optional location,
-         * tracks, and highlights to apply once the view attaches. It is applied
-         * by the afterAttach autorun and then cleared (setInit(undefined)), so a
-         * saved session never retains it. Shared by all three launch surfaces —
-         * URL params, createViewState(), and session/config JSON. example:
-         * ```json
-         * {
-         *   "assembly": "hg19",
-         *   "loc": "chr1:1,000,000-2,000,000",
-         *   "tracks": ["genes", "variants"]
-         * }
-         * ```
-         */
-        init: types.frozen(),
+         * transient launch state: the settings written on the view object that
+         * need resolving before they can be view state — an assembly, a
+         * location, track recipes, highlights. `preProcessSnapshot` moves them
+         * here off the snapshot, the afterAttach autorun applies them and
+         * clears this, so a saved session never retains it. Not written by
+         * hand: author every setting directly on the view.
+         */
+        launch: types.frozen(),
     }))
         .volatile(self => {
         // typed locals so `unknown`/`Record` aren't narrowed to `undefined`/`{}`; inline
@@ -413,6 +412,14 @@ export function stateModelFactory(pluginManager) {
         // ahead of every other getter so that the ~300 reads of `self.bpPerPx` /
         // `self.offsetPx` across the codebase go on resolving by name. Only the
         // writes had to move, and they are six actions below.
+        /**
+         * #getter
+         * the launch state that still has something to apply — the gate every
+         * loading and error path below reads.
+         */
+        get pendingLaunch() {
+            return pendingLaunch(self.launch);
+        },
         /**
          * #getter
          * corresponds roughly to the zoom level, base-pairs per pixel.
@@ -555,10 +562,7 @@ export function stateModelFactory(pluginManager) {
          */
         get assemblyErrors() {
             const { assemblyManager } = getSession(self);
-            return self.assemblyNames
-                .map(name => assemblyManager.get(name)?.error)
-                .filter(e => !!e)
-                .join(', ');
+            return assemblyErrorMessage(assemblyManager, self.assemblyNames);
         },
         /**
          * #getter
@@ -575,8 +579,8 @@ export function stateModelFactory(pluginManager) {
          * and error checks resolve it directly through here.
          */
         get initAssembly() {
-            return self.init
-                ? getSession(self).assemblyManager.get(self.init.assembly)
+            return self.pendingLaunch
+                ? getSession(self).assemblyManager.get(self.pendingLaunch.assembly)
                 : undefined;
         },
         /**
@@ -587,7 +591,7 @@ export function stateModelFactory(pluginManager) {
                 return false;
             }
             // if init is set, wait for that assembly to have regions loaded
-            if (self.init) {
+            if (self.pendingLaunch) {
                 const asm = this.initAssembly;
                 return !!(asm?.initialized && asm.regions);
             }
@@ -606,7 +610,7 @@ export function stateModelFactory(pluginManager) {
          * displayed assemblies that hasn't finished loading.
          */
         get loadingAssembly() {
-            return self.init
+            return self.pendingLaunch
                 ? this.initAssembly
                 : getSession(self).assemblyManager.loadingAssembly(self.assemblyNames);
         },
@@ -646,7 +650,7 @@ export function stateModelFactory(pluginManager) {
          * #getter
          */
         get hasSomethingToShow() {
-            return this.hasDisplayedRegions || !!self.init;
+            return this.hasDisplayedRegions || !!self.pendingLaunch;
         },
         /**
          * #getter
@@ -656,7 +660,7 @@ export function stateModelFactory(pluginManager) {
          * would mount over empty regions and pxToBp/hover would throw.
          *
          * **Not dotplot's or synteny's `initPending`**, which is the bare
-         * `!!self.init` — "an init blob has not been applied" — and which those
+         * `!!self.pendingLaunch` — "an init blob has not been applied" — and which those
          * views read from their `settled` gate rather than from `showLoading`.
          * This one is narrower on purpose: it closes only the window where there
          * is nothing on screen. Once navigation has produced regions the view is
@@ -666,7 +670,7 @@ export function stateModelFactory(pluginManager) {
          * theirs.
          */
         get awaitingInitNavigation() {
-            return !!self.init && !this.hasDisplayedRegions;
+            return !!self.pendingLaunch && !this.hasDisplayedRegions;
         },
         /**
          * #getter
@@ -935,17 +939,17 @@ export function stateModelFactory(pluginManager) {
                 return this.assembliesNotFound;
             }
             // Check init assembly for errors (displayedRegions may be empty during init)
-            if (self.init) {
+            if (self.pendingLaunch) {
                 // `assembly` is required by InitState, but init is a frozen blob and
                 // hand-authored JSON is what fills it, so the type is not a guarantee.
                 // Naming the authoring mistake beats the downstream symptom, which is
                 // the literal string "Assembly undefined not found".
-                if (!self.init.assembly) {
+                if (!self.pendingLaunch.assembly) {
                     return 'LinearGenomeView init needs an "assembly"';
                 }
                 const asm = this.initAssembly;
                 if (!asm) {
-                    return `Assembly ${self.init.assembly} not found`;
+                    return `Assembly ${self.pendingLaunch.assembly} not found`;
                 }
                 if (asm.error) {
                     return asm.error;
@@ -1221,6 +1225,16 @@ export function stateModelFactory(pluginManager) {
         hideTrack(trackId) {
             return hideTrackGeneric(self, trackId);
         },
+    }))
+        .actions(self => ({
+        /**
+         * #action
+         * showTrack for a track whose display state model may be lazily
+         * loaded: loads it, then shows
+         */
+        async launchTrack(trackId, initialSnapshot = {}, displayInitialSnapshot = {}, inlineConf) {
+            return launchTrackGeneric(self, trackId, initialSnapshot, displayInitialSnapshot, inlineConf);
+        },
     }))
         .actions(self => ({
         /**
@@ -1289,6 +1303,13 @@ export function stateModelFactory(pluginManager) {
         toggleTrack(trackId) {
             return toggleTrackGeneric(self, trackId);
         },
+        /**
+         * #action
+         * toggleTrack with launchTrack's loading behavior
+         */
+        async launchToggleTrack(trackId) {
+            return launchToggleTrackGeneric(self, trackId);
+        },
         /**
          * #action
          */
@@ -1402,8 +1423,8 @@ export function stateModelFactory(pluginManager) {
         /**
          * #action
          */
-        setInit(arg) {
-            self.init = arg;
+        setLaunch(launch) {
+            self.launch = launch;
         },
         /**
          * #method
@@ -1866,6 +1887,11 @@ export function stateModelFactory(pluginManager) {
              * The seam is the one that must survive: regions lay out contiguously,
              * so it is all that separates two of them.
              */
+            // Annotated with the shape spelled out rather than as `PaddingSpan`,
+            // because the API doc's type column is where a host drawing its own
+            // chrome reads the field names, and a named type prints as its name.
+            // `spans` and NO_PADDING_SPANS are both `PaddingSpan[]`, so the two
+            // cannot drift without failing here.
             get paddingSpans() {
                 const { blocks, offsetPx: firstBlockOffset } = this.staticBlocks;
                 const spans = [];
@@ -1892,7 +1918,14 @@ export function stateModelFactory(pluginManager) {
                         });
                     }
                 }
-                return spans;
+                // One shared array when there is nothing to draw, so the computed's
+                // value repeats and MobX's `===` stops the chain here. This is the
+                // COMMON case, not an edge one: a view sitting inside one contig has
+                // no region seam, no elision and no boundary, and that is where a
+                // reader spends nearly all of a session. A fresh `[]` each frame
+                // instead re-rendered a PaddingBlocks per track plus one for the
+                // container, every frame of every gesture, to draw nothing.
+                return spans.length > 0 ? spans : NO_PADDING_SPANS;
             },
             /**
              * #getter
@@ -1962,6 +1995,32 @@ export function stateModelFactory(pluginManager) {
                     };
                 });
             },
+            /**
+             * #getter
+             * Right edge (px, viewport-relative) of the on-screen content, clamped
+             * to the track — where a right-pinned overlay such as a wiggle's colour
+             * or score legend belongs, rather than out in the empty gutter the
+             * regions can leave at whole-genome zoom. `@jbrowse/display-kit`'s
+             * `contentRightEdgePx` states the rule; an SVG export applies the same
+             * one against the export's canvas width instead of this track's.
+             *
+             * Published as a SCALAR on purpose. `visibleRegions` rebuilds a fresh
+             * array of fresh objects on every pan and zoom frame, so a component
+             * that derived this number itself re-rendered on every frame of every
+             * gesture — to produce, whenever content fills the track, the unchanged
+             * `trackWidthPx`. Reading the scalar lets MobX's `===` stop the chain at
+             * this computed instead. Measured over 20 zoom frames: the wiggle
+             * family's three body instances fell from 66 renders to 7.
+             */
+            get contentRightEdgePx() {
+                // The `trackWidthPx` rule sends a DISPLAY to `model.canvasWidthPx`
+                // so it cannot pick the wrong one of four view getters. This is the
+                // view, publishing its own geometry, and `canvasWidthPx` is defined
+                // as exactly this host's `trackWidthPx` (MultiRegionDisplayMixin) —
+                // the same source of truth, read from the side that owns it.
+                // eslint-disable-next-line no-restricted-syntax
+                return contentRightEdgePx(this.visibleRegions, self.trackWidthPx);
+            },
             /**
              * #getter
              * visibleRegions expanded by a half-screen buffer on each side,
@@ -2386,13 +2445,15 @@ export function stateModelFactory(pluginManager) {
          * navigating to the locstring
          * @param grow - optional multiplier to expand the region by (e.g., 0.2
          * adds 20% padding on each side)
+         * @param opts - `showHitTrack: false` keeps a text-search hit from also
+         * showing the track its index was built from
          * @returns whether the view moved. A multi-hit search raises the picker
          * instead of navigating, and both resolve — see `handleSelectedRegion`.
          */
         // annotated, not inferred: the same type cycle `showTrack` names. Left to
         // infer, the `boolean` reaches this model's type through `self` and 180
         // unrelated files lose their parameter types to it.
-        async navToLocString(input, optAssemblyName, grow) {
+        async navToLocString(input, optAssemblyName, grow, opts) {
             const { assemblyNames } = self;
             const session = getSession(self);
             const { assemblyManager } = session;
@@ -2407,6 +2468,7 @@ export function stateModelFactory(pluginManager) {
                 input,
                 assemblyName,
                 grow,
+                showHitTrack: opts?.showHitTrack,
                 model: self,
             });
         },
@@ -2697,7 +2759,8 @@ export function stateModelFactory(pluginManager) {
         afterAttach() {
             doAfterAttach(self);
         },
-    }))
+    }));
+    return withLaunchInput(model, lgvLaunchKeys)
         .preProcessSnapshot((snap) => {
         if (!snap) {
             return snap;
@@ -2739,23 +2802,24 @@ export function stateModelFactory(pluginManager) {
         };
     })
         .postProcessSnapshot(snap => {
-        // init is transient launch state, never persisted. showCenterLine is
+        // launch is transient, never persisted. showCenterLine is
         // purely a localStorage-backed preference (see setupLocalStorageAutorun
         // in afterAttach.ts) and is never persisted into session snapshots. The
         // remaining fields are also localStorage-backed, but still persist when
         // non-default: their strip baseline is the universal default (hardcoded
         // here), not the localStorage-derived creation default, so a
         // localStorage-set value stays portable across browsers.
-        const { init, showCenterLine, showCytobands, trackLabels, colorByCDS, showAminoAcids, showTrackOutlines, ...rest } = snap;
+        const { launch, showCenterLine, showCytobands, trackLabels, colorByCDS, showAminoAcids, showTrackOutlines, ...rest } = snap;
         return {
             ...rest,
-            // keep init until displayedRegions exist, so a snapshot taken before the
-            // launch autorun navigates (e.g. autosave firing mid-load) can still
-            // rebuild the view instead of dropping to the import form.
-            // displayedRegions is stripDefault, so it's absent (not []) when empty —
-            // the optional chain is runtime-necessary despite the non-nullish type.
+            // keep the launch state until displayedRegions exist, so a snapshot
+            // taken before the launch autorun navigates (e.g. autosave firing
+            // mid-load) can still rebuild the view instead of dropping to the
+            // import form. displayedRegions is stripDefault, so it's absent (not
+            // []) when empty — the optional chain is runtime-necessary despite the
+            // non-nullish type.
             // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition
-            ...(init && !snap.displayedRegions?.length ? { init } : {}),
+            ...(launch && !snap.displayedRegions?.length ? { launch } : {}),
             ...(!showCytobands ? { showCytobands } : {}),
             ...(trackLabels ? { trackLabels } : {}),
             ...(colorByCDS ? { colorByCDS } : {}),

package/esm/LinearGenomeView/svgcomponents/figureContract.js

@@ -1,25 +1,25 @@
 import { useEffect, useRef } from 'react';
 import { svgNodeId } from '@jbrowse/core/svg/svgId';
+import { contractReportsOn, reportContractViolation, } from '@jbrowse/render-core/contractReports';
 /**
- * Dev-only checks that a live SVG figure is being used the way it can work.
- * No-ops in production.
+ * Checks that a live SVG figure is being used the way it can work.
  *
  * `useViewSvgFigure` publishes a figure whose two halves are drawn at different
  * moments and only agree by construction, and both ways of breaking that are
  * invisible in the output: the drawing is still a plausible picture of
  * somewhere, just not of one moment or not with its own clips. So the run
  * reports instead, through the `[jbrowse <family> contract]` channel every
- * dev-only check in the tree uses — `config/jest/contractGate.js` fails the test
- * that collects one, and ARCHITECTURAL_LIMITS.md §"Ordering is the contract" is
- * the register. `figure` rather than `svg-figure` because the gate's family
- * pattern is `\w+`, which a hyphen is not.
+ * check in the tree uses — `config/jest/contractGate.js` fails the test that
+ * collects one, and ARCHITECTURAL_LIMITS.md §"Ordering is the contract" is the
+ * register. `figure` rather than `svg-figure` because the gate's family pattern
+ * is `\w+`, which a hyphen is not.
  *
- * `console.error` and never a throw, as the rest of that family: a figure is
- * chrome a host renders beside its own, and taking the host's tree down over a
- * drawing is worse than the drawing being wrong.
+ * Reported and never thrown, as the rest of that family: a figure is chrome a
+ * host renders beside its own, and taking the host's tree down over a drawing
+ * is worse than the drawing being wrong.
  */
 function report(message) {
-    console.error(`[jbrowse figure contract] ${message}`);
+    reportContractViolation('figure', message);
 }
 // Live figures per view, keyed the way their SVG ids are. A count rather than a
 // flag: the report belongs on the second mount, and the first has to survive the
@@ -43,9 +43,6 @@ const figuresPerView = new Map();
  */
 export function useOneFigurePerView(view) {
     useEffect(() => {
-        if (process.env.NODE_ENV === 'production') {
-            return undefined;
-        }
         // captured, not re-derived on cleanup: by then the view may have left the
         // tree, and `svgNodeId` walks it
         const key = svgNodeId(view);
@@ -99,7 +96,10 @@ export function useFrozenFigureContract(ref, snapshot) {
     rendered.current = snapshot;
     useEffect(() => {
         const el = ref.current;
-        if (process.env.NODE_ENV === 'production' || !el) {
+        // the one check here with a cost of its own — a `MutationObserver` over the
+        // whole figure subtree — so unlike its neighbour it asks whether the
+        // channel is armed rather than running and reporting into it
+        if (!contractReportsOn() || !el) {
             return undefined;
         }
         const observer = new MutationObserver(() => {

package/esm/LinearGenomeView/svgcomponents/useViewSvgFigure.js

@@ -101,8 +101,8 @@ async function renderFigure(view, opts) {
  */
 const FrozenSvgFigure = memo(function FrozenSvgFigure({ view, snapshot, }) {
     const { width, height, margin, theme } = snapshot;
-    // dev-only, and it watches for the one thing this component cannot enforce:
-    // an observer INSIDE the tree, which the memo above is not between
+    // 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}`, 

package/esm/LinearGenomeView/types.d.ts

@@ -41,4 +41,4 @@ export interface InitState {
     nav?: boolean;
     highlight?: (string | HighlightType)[];
 }
-export type LinearGenomeViewLaunchProps = Partial<Omit<SnapshotIn<LinearGenomeViewStateModel>, keyof InitState | 'id' | 'type' | 'init'>>;
+export type LinearGenomeViewLaunchProps = Partial<Omit<SnapshotIn<LinearGenomeViewStateModel>, keyof InitState | 'id' | 'type' | 'launch'>>;