@jbrowse/plugin-linear-genome-view 2.1.7 → 2.2.0

package/esm/LinearGenomeView/index.js

@@ -36,7 +36,7 @@ function calculateVisibleLocStrings(contentBlocks) {
     if (!contentBlocks.length) {
         return '';
     }
-    const isSingleAssemblyName = contentBlocks.every(block => block.assemblyName === contentBlocks[0].assemblyName);
+    const isSingleAssemblyName = contentBlocks.every(b => b.assemblyName === contentBlocks[0].assemblyName);
     const locs = contentBlocks.map(block => assembleLocString({
         ...block,
         start: Math.round(block.start),
@@ -57,30 +57,84 @@ function localStorageGetItem(item) {
         ? localStorage.getItem(item)
         : undefined;
 }
+/**
+ * #stateModel LinearGenomeView
+ */
 export function stateModelFactory(pluginManager) {
     return types
         .compose(BaseViewModel, types.model('LinearGenomeView', {
+        /**
+         * #property
+         */
         id: ElementId,
+        /**
+         * #property
+         */
         type: types.literal('LinearGenomeView'),
+        /**
+         * #property
+         * corresponds roughly to the horizontal scroll of the LGV
+         */
         offsetPx: 0,
+        /**
+         * #property
+         * corresponds roughly to the zoom level, base-pairs per pixel
+         */
         bpPerPx: 1,
+        /**
+         * #property
+         * currently displayed regions, can be a single chromosome, arbitrary subsections,
+         * or the entire  set of chromosomes in the genome, but it not advised to use the
+         * entire set of chromosomes if your assembly is very fragmented
+         */
         displayedRegions: types.array(MUIRegion),
-        // we use an array for the tracks because the tracks are displayed in a
-        // specific order that we need to keep.
+        /**
+         * #property
+         * array of currently displayed tracks state models instances
+         */
         tracks: types.array(pluginManager.pluggableMstType('track', 'stateModel')),
+        /**
+         * #property
+         * array of currently displayed tracks state model's
+         */
         hideHeader: false,
+        /**
+         * #property
+         */
         hideHeaderOverview: false,
+        /**
+         * #property
+         */
         hideNoTracksActive: false,
+        /**
+         * #property
+         */
         trackSelectorType: types.optional(types.enumeration(['hierarchical']), 'hierarchical'),
+        /**
+         * #property
+         * how to display the track labels, can be "overlapping", "offset", or "hidden"
+         */
         trackLabels: types.optional(types.string, () => localStorageGetItem('lgv-trackLabels') || 'overlapping'),
+        /**
+         * #property
+         * show the "center line"
+         */
         showCenterLine: types.optional(types.boolean, () => {
             const setting = localStorageGetItem('lgv-showCenterLine');
             return setting !== undefined && setting !== null ? !!+setting : false;
         }),
+        /**
+         * #property
+         * show the "cytobands" in the overview scale bar
+         */
         showCytobandsSetting: types.optional(types.boolean, () => {
             const setting = localStorageGetItem('lgv-showCytobands');
             return setting !== undefined && setting !== null ? !!+setting : true;
         }),
+        /**
+         * #property
+         * show the "gridlines" in the track area
+         */
         showGridlines: true,
     }))
         .volatile(() => ({
@@ -103,15 +157,24 @@ export function stateModelFactory(pluginManager) {
         seqDialogDisplayed: false,
     }))
         .views(self => ({
+        /**
+         * #getter
+         */
         get width() {
             if (self.volatileWidth === undefined) {
                 throw new Error('width undefined, make sure to check for model.initialized');
             }
             return self.volatileWidth;
         },
+        /**
+         * #getter
+         */
         get interRegionPaddingWidth() {
             return INTER_REGION_PADDING_WIDTH;
         },
+        /**
+         * #getter
+         */
         get assemblyNames() {
             return [
                 ...new Set(self.displayedRegions.map(region => region.assemblyName)),
@@ -259,33 +322,60 @@ export function stateModelFactory(pluginManager) {
         },
     }))
         .actions(self => ({
+        /**
+         * #action
+         */
         setShowCytobands(flag) {
             self.showCytobandsSetting = flag;
             localStorage.setItem('lgv-showCytobands', `${+flag}`);
         },
+        /**
+         * #action
+         */
         setWidth(newWidth) {
             self.volatileWidth = newWidth;
         },
+        /**
+         * #action
+         */
         setError(error) {
             self.volatileError = error;
         },
+        /**
+         * #action
+         */
         toggleHeader() {
             self.hideHeader = !self.hideHeader;
         },
+        /**
+         * #action
+         */
         toggleHeaderOverview() {
             self.hideHeaderOverview = !self.hideHeaderOverview;
         },
+        /**
+         * #action
+         */
         toggleNoTracksActive() {
             self.hideNoTracksActive = !self.hideNoTracksActive;
         },
+        /**
+         * #action
+         */
         toggleShowGridlines() {
             self.showGridlines = !self.showGridlines;
         },
+        /**
+         * #action
+         */
         scrollTo(offsetPx) {
             const newOffsetPx = clamp(offsetPx, self.minOffset, self.maxOffset);
             self.offsetPx = newOffsetPx;
             return newOffsetPx;
         },
+        /**
+         * #action
+         */
         zoomTo(bpPerPx) {
             const newBpPerPx = clamp(bpPerPx, self.minBpPerPx, self.maxBpPerPx);
             if (newBpPerPx === self.bpPerPx) {
@@ -303,22 +393,37 @@ export function stateModelFactory(pluginManager) {
                 viewWidth / 2));
             return newBpPerPx;
         },
+        /**
+         * #action
+         * sets offsets used in the get sequence dialog
+         */
         setOffsets(left, right) {
-            // sets offsets used in the get sequence dialog
             self.leftOffset = left;
             self.rightOffset = right;
         },
+        /**
+         * #action
+         */
         setSearchResults(results, query) {
             self.searchResults = results;
             self.searchQuery = query;
         },
+        /**
+         * #action
+         */
         setGetSequenceDialogOpen(open) {
             self.seqDialogDisplayed = open;
         },
+        /**
+         * #action
+         */
         setNewView(bpPerPx, offsetPx) {
             this.zoomTo(bpPerPx);
             this.scrollTo(offsetPx);
         },
+        /**
+         * #action
+         */
         horizontallyFlip() {
             self.displayedRegions = cast(self.displayedRegions
                 .slice()
@@ -326,6 +431,9 @@ export function stateModelFactory(pluginManager) {
                 .map(region => ({ ...region, reversed: !region.reversed })));
             this.scrollTo(self.totalBp / self.bpPerPx - self.offsetPx - self.width);
         },
+        /**
+         * #action
+         */
         showTrack(trackId, initialSnapshot = {}, displayInitialSnapshot = {}) {
             const schema = pluginManager.pluggableConfigSchemaType('track');
             const conf = resolveIdentifier(schema, getRoot(self), trackId);
@@ -370,6 +478,9 @@ export function stateModelFactory(pluginManager) {
         },
     }))
         .actions(self => ({
+        /**
+         * #action
+         */
         moveTrack(movingId, targetId) {
             const oldIndex = self.tracks.findIndex(track => track.id === movingId);
             if (oldIndex === -1) {
@@ -383,6 +494,9 @@ export function stateModelFactory(pluginManager) {
             self.tracks.splice(oldIndex, 1);
             self.tracks.splice(newIndex, 0, track);
         },
+        /**
+         * #action
+         */
         closeView() {
             const parent = getContainingView(self);
             if (parent) {
@@ -396,6 +510,9 @@ export function stateModelFactory(pluginManager) {
                 getSession(self).removeView(self);
             }
         },
+        /**
+         * #action
+         */
         toggleTrack(trackId) {
             // if we have any tracks with that configuration, turn them off
             const hiddenCount = self.hideTrack(trackId);
@@ -404,18 +521,30 @@ export function stateModelFactory(pluginManager) {
                 self.showTrack(trackId);
             }
         },
+        /**
+         * #action
+         */
         setTrackLabels(setting) {
             self.trackLabels = setting;
             localStorage.setItem('lgv-trackLabels', setting);
         },
+        /**
+         * #action
+         */
         toggleCenterLine() {
             self.showCenterLine = !self.showCenterLine;
             localStorage.setItem('lgv-showCenterLine', `${+self.showCenterLine}`);
         },
+        /**
+         * #action
+         */
         setDisplayedRegions(regions) {
             self.displayedRegions = cast(regions);
             self.zoomTo(self.bpPerPx);
         },
+        /**
+         * #action
+         */
         activateTrackSelector() {
             if (self.trackSelectorType === 'hierarchical') {
                 const session = getSession(self);
@@ -428,6 +557,7 @@ export function stateModelFactory(pluginManager) {
             throw new Error(`invalid track selector type ${self.trackSelectorType}`);
         },
         /**
+         * #method
          * Helper method for the fetchSequence.
          * Retrieves the corresponding regions that were selected by the rubberband
          *
@@ -449,38 +579,51 @@ export function stateModelFactory(pluginManager) {
                 end: Math.ceil(region.end),
             }));
         },
-        // schedule something to be run after the next time displayedRegions is set
+        /**
+         * #action
+         * schedule something to be run after the next time displayedRegions is set
+         */
         afterDisplayedRegionsSet(cb) {
             self.afterDisplayedRegionsSetCallbacks.push(cb);
         },
+        /**
+         * #action
+         */
         horizontalScroll(distance) {
             const oldOffsetPx = self.offsetPx;
             // newOffsetPx is the actual offset after the scroll is clamped
             const newOffsetPx = self.scrollTo(self.offsetPx + distance);
             return newOffsetPx - oldOffsetPx;
         },
+        /**
+         * #action
+         */
         center() {
             const centerBp = self.totalBp / 2;
             const centerPx = centerBp / self.bpPerPx;
             self.scrollTo(Math.round(centerPx - self.width / 2));
         },
+        /**
+         * #action
+         */
         showAllRegions() {
             self.zoomTo(self.maxBpPerPx);
             this.center();
         },
+        /**
+         * #action
+         */
         showAllRegionsInAssembly(assemblyName) {
             const session = getSession(self);
             const { assemblyManager } = session;
             if (!assemblyName) {
-                const assemblyNames = [
-                    ...new Set(self.displayedRegions.map(region => region.assemblyName)),
-                ];
-                if (assemblyNames.length > 1) {
-                    session.notify(`Can't perform this with multiple assemblies currently`);
+                const names = new Set(self.displayedRegions.map(r => r.assemblyName));
+                if (names.size > 1) {
+                    session.notify(`Can't perform operation with multiple assemblies currently`);
                     return;
                 }
                 ;
-                [assemblyName] = assemblyNames;
+                [assemblyName] = [...names];
             }
             const assembly = assemblyManager.get(assemblyName);
             if (assembly) {
@@ -492,13 +635,22 @@ export function stateModelFactory(pluginManager) {
                 }
             }
         },
+        /**
+         * #action
+         */
         setDraggingTrackId(idx) {
             self.draggingTrackId = idx;
         },
+        /**
+         * #action
+         */
         setScaleFactor(factor) {
             self.scaleFactor = factor;
         },
-        // this "clears the view" and makes the view return to the import form
+        /**
+         * #action
+         * this "clears the view" and makes the view return to the import form
+         */
         clearView() {
             this.setDisplayedRegions([]);
             self.tracks.clear();
@@ -508,6 +660,10 @@ export function stateModelFactory(pluginManager) {
             self.scrollTo(0);
             self.zoomTo(10);
         },
+        /**
+         * #action
+         * creates an svg export and save using FileSaver
+         */
         async exportSvg(opts = {}) {
             // eslint-disable-next-line @typescript-eslint/no-explicit-any
             const html = await renderToSvg(self, opts);
@@ -517,6 +673,10 @@ export function stateModelFactory(pluginManager) {
     }))
         .actions(self => {
         let cancelLastAnimation = () => { };
+        /**
+         * #action
+         * perform animated slide
+         */
         function slide(viewWidths) {
             const [animate, cancelAnimation] = springAnimate(self.offsetPx, self.offsetPx + self.width * viewWidths, self.scrollTo);
             cancelLastAnimation();
@@ -527,6 +687,10 @@ export function stateModelFactory(pluginManager) {
     })
         .actions(self => {
         let cancelLastAnimation = () => { };
+        /**
+         * #action
+         * perform animated zoom
+         */
         function zoom(targetBpPerPx) {
             self.zoomTo(self.bpPerPx);
             if (
@@ -548,17 +712,30 @@ export function stateModelFactory(pluginManager) {
         return { zoom };
     })
         .views(self => ({
+        /**
+         * #getter
+         */
         get canShowCytobands() {
             return self.displayedRegions.length === 1 && this.anyCytobandsExist;
         },
+        /**
+         * #getter
+         */
         get showCytobands() {
             return this.canShowCytobands && self.showCytobandsSetting;
         },
+        /**
+         * #getter
+         */
         get anyCytobandsExist() {
             const { assemblyManager } = getSession(self);
-            const { assemblyNames } = self;
-            return assemblyNames.some(asm => { var _a, _b; return (_b = (_a = assemblyManager.get(asm)) === null || _a === void 0 ? void 0 : _a.cytobands) === null || _b === void 0 ? void 0 : _b.length; });
+            return self.assemblyNames.some(a => { var _a, _b; return (_b = (_a = assemblyManager.get(a)) === null || _a === void 0 ? void 0 : _a.cytobands) === null || _b === void 0 ? void 0 : _b.length; });
         },
+        /**
+         * #getter
+         * the cytoband is displayed to the right of the chromosome name,
+         * and that offset is calculated manually with this method
+         */
         get cytobandOffset() {
             return this.showCytobands
                 ? measureText(self.displayedRegions[0].refName, 12) + 15
@@ -566,6 +743,10 @@ export function stateModelFactory(pluginManager) {
         },
     }))
         .views(self => ({
+        /**
+         * #method
+         * return the view menu items
+         */
         menuItems() {
             const { canShowCytobands, showCytobands } = self;
             const session = getSession(self);
@@ -708,6 +889,15 @@ export function stateModelFactory(pluginManager) {
         let currentlyCalculatedStaticBlocks;
         let stringifiedCurrentlyCalculatedStaticBlocks = '';
         return {
+            /**
+             * #getter
+             * static blocks are an important concept jbrowse uses to avoid
+             * re-rendering when you scroll to the side. when you horizontally
+             * scroll to the right, old blocks to the left may be removed, and
+             * new blocks may be instantiated on the right. tracks may use the
+             * static blocks to render their data for the region represented by
+             * the block
+             */
             get staticBlocks() {
                 const ret = calculateStaticBlocks(self);
                 const sret = JSON.stringify(ret);
@@ -717,27 +907,48 @@ export function stateModelFactory(pluginManager) {
                 }
                 return currentlyCalculatedStaticBlocks;
             },
+            /**
+             * #getter
+             * dynamic blocks represent the exact coordinates of the currently
+             * visible genome regions on the screen. they are similar to static
+             * blocks, but statcic blocks can go offscreen while dynamic blocks
+             * represent exactly what is on screen
+             */
             get dynamicBlocks() {
                 return calculateDynamicBlocks(self);
             },
+            /**
+             * #getter
+             * rounded dynamic blocks are dynamic blocks without fractions of bp
+             */
             get roundedDynamicBlocks() {
-                return this.dynamicBlocks.contentBlocks.map(block => {
-                    return {
-                        ...block,
-                        start: Math.floor(block.start),
-                        end: Math.ceil(block.end),
-                    };
-                });
+                return this.dynamicBlocks.contentBlocks.map(block => ({
+                    ...block,
+                    start: Math.floor(block.start),
+                    end: Math.ceil(block.end),
+                }));
             },
+            /**
+             * #getter
+             * a single "combo-locstring" representing all the regions visible
+             * on the screen
+             */
             get visibleLocStrings() {
                 return calculateVisibleLocStrings(this.dynamicBlocks.contentBlocks);
             },
+            /**
+             * #getter
+             * same as visibleLocStrings, but only updated every 300ms
+             */
             get coarseVisibleLocStrings() {
                 return calculateVisibleLocStrings(self.coarseDynamicBlocks);
             },
         };
     })
         .actions(self => ({
+        /**
+         * #action
+         */
         setCoarseDynamicBlocks(blocks) {
             self.coarseDynamicBlocks = blocks.contentBlocks;
             self.coarseTotalBp = blocks.totalBp;
@@ -752,6 +963,7 @@ export function stateModelFactory(pluginManager) {
     }))
         .actions(self => ({
         /**
+         * #action
          * offset is the base-pair-offset in the displayed region, index is the index of the
          * displayed region in the linear genome view
          *
@@ -761,7 +973,14 @@ export function stateModelFactory(pluginManager) {
         moveTo(start, end) {
             moveTo(self, start, end);
         },
-        navToLocString(locString, optAssemblyName) {
+        /**
+         * #action
+         * navigate to the given locstring
+         *
+         * @param locString - e.g. "chr1:1-100"
+         * @param optAssemblyName - (optional) the assembly name to use when navigating to the locstring
+         */
+        async navToLocString(locString, optAssemblyName) {
             const { assemblyNames } = self;
             const { assemblyManager } = getSession(self);
             const { isValidRefName } = assemblyManager;
@@ -771,6 +990,9 @@ export function stateModelFactory(pluginManager) {
                 .split(/(\s+)/)
                 .map(f => f.trim())
                 .filter(f => !!f);
+            if (assemblyName) {
+                await assemblyManager.waitForAssembly(assemblyName);
+            }
             // first try interpreting as a whitespace-separated sequence of
             // multiple locstrings
             try {
@@ -791,9 +1013,9 @@ export function stateModelFactory(pluginManager) {
                     throw e;
                 }
             }
-            const locations = parsedLocStrings === null || parsedLocStrings === void 0 ? void 0 : parsedLocStrings.map(region => {
+            const locations = await Promise.all(parsedLocStrings === null || parsedLocStrings === void 0 ? void 0 : parsedLocStrings.map(async (region) => {
                 const asmName = region.assemblyName || assemblyName;
-                const asm = assemblyManager.get(asmName);
+                const asm = await assemblyManager.waitForAssembly(asmName);
                 const { refName } = region;
                 if (!asm) {
                     throw new Error(`assembly ${asmName} not found`);
@@ -806,7 +1028,7 @@ export function stateModelFactory(pluginManager) {
                 if (!canonicalRefName) {
                     throw new Error(`Could not find refName ${refName} in ${asm.name}`);
                 }
-                const parentRegion = regions.find(region => region.refName === canonicalRefName);
+                const parentRegion = regions.find(r => r.refName === canonicalRefName);
                 if (!parentRegion) {
                     throw new Error(`Could not find refName ${refName} in ${asmName}`);
                 }
@@ -815,7 +1037,7 @@ export function stateModelFactory(pluginManager) {
                     assemblyName: asmName,
                     parentRegion,
                 };
-            });
+            }));
             if (locations.length === 1) {
                 const loc = locations[0];
                 self.setDisplayedRegions([
@@ -836,6 +1058,7 @@ export function stateModelFactory(pluginManager) {
             }
         },
         /**
+         * #action
          * Navigate to a location based on its refName and optionally start, end,
          * and assemblyName. Can handle if there are multiple displayedRegions
          * from same refName. Only navigates to a location if it is entirely
@@ -844,11 +1067,14 @@ export function stateModelFactory(pluginManager) {
          *
          * Throws an error if navigation was unsuccessful
          *
-         * @param location - a proposed location to navigate to
+         * @param query - a proposed location to navigate to
          */
         navTo(query) {
             this.navToMultiple([query]);
         },
+        /**
+         * #action
+         */
         navToMultiple(locations) {
             const firstLocation = locations[0];
             let { refName } = firstLocation;
@@ -950,6 +1176,9 @@ export function stateModelFactory(pluginManager) {
         },
     }))
         .views(self => ({
+        /**
+         * #method
+         */
         rubberBandMenuItems() {
             return [
                 {
@@ -967,10 +1196,14 @@ export function stateModelFactory(pluginManager) {
                 },
             ];
         },
+        /**
+         * #method
+         */
         bpToPx({ refName, coord, regionNumber, }) {
             return bpToPx({ refName, coord, regionNumber, self });
         },
         /**
+         * #method
          * scrolls the view to center on the given bp. if that is not in any
          * of the displayed regions, does nothing
          * @param coord - basepair at which you want to center the view
@@ -987,9 +1220,15 @@ export function stateModelFactory(pluginManager) {
                 self.scrollTo(Math.round(centerPx.offsetPx - self.width / 2));
             }
         },
+        /**
+         * #method
+         */
         pxToBp(px) {
             return pxToBp(self, px);
         },
+        /**
+         * #getter
+         */
         get centerLineInfo() {
             return self.displayedRegions.length
                 ? this.pxToBp(self.width / 2)