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

package/dist/LinearGenomeView/index.js

@@ -65,12 +65,13 @@ const ZoomControls_1 = __importDefault(require("./components/ZoomControls"));
 exports.ZoomControls = ZoomControls_1.default;
 const LinearGenomeView_1 = __importDefault(require("./components/LinearGenomeView"));
 exports.LinearGenomeView = LinearGenomeView_1.default;
+// lazies
 const SequenceSearchDialog = (0, react_1.lazy)(() => Promise.resolve().then(() => __importStar(require('./components/SequenceSearchDialog'))));
 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 => (0, util_1.assembleLocString)({
         ...block,
         start: Math.round(block.start),
@@ -91,30 +92,87 @@ function localStorageGetItem(item) {
         ? localStorage.getItem(item)
         : undefined;
 }
+/**
+ * #stateModel LinearGenomeView
+ */
 function stateModelFactory(pluginManager) {
     return mobx_state_tree_1.types
         .compose(models_1.BaseViewModel, mobx_state_tree_1.types.model('LinearGenomeView', {
+        /**
+         * #property
+         */
         id: mst_1.ElementId,
+        /**
+         * #property
+         * this is a string instead of the const literal 'LinearGenomeView' to reduce some
+         * typescripting strictness, but you should pass the string 'LinearGenomeView' to
+         * the model explicitly
+         */
         type: mobx_state_tree_1.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: mobx_state_tree_1.types.array(mst_1.Region),
-        // 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: mobx_state_tree_1.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: mobx_state_tree_1.types.optional(mobx_state_tree_1.types.enumeration(['hierarchical']), 'hierarchical'),
+        /**
+         * #property
+         * how to display the track labels, can be "overlapping", "offset", or "hidden"
+         */
         trackLabels: mobx_state_tree_1.types.optional(mobx_state_tree_1.types.string, () => localStorageGetItem('lgv-trackLabels') || 'overlapping'),
+        /**
+         * #property
+         * show the "center line"
+         */
         showCenterLine: mobx_state_tree_1.types.optional(mobx_state_tree_1.types.boolean, () => {
             const setting = localStorageGetItem('lgv-showCenterLine');
             return setting !== undefined && setting !== null ? !!+setting : false;
         }),
+        /**
+         * #property
+         * show the "cytobands" in the overview scale bar
+         */
         showCytobandsSetting: mobx_state_tree_1.types.optional(mobx_state_tree_1.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(() => ({
@@ -137,15 +195,24 @@ 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 exports.INTER_REGION_PADDING_WIDTH;
         },
+        /**
+         * #getter
+         */
         get assemblyNames() {
             return [
                 ...new Set(self.displayedRegions.map(region => region.assemblyName)),
@@ -153,14 +220,23 @@ function stateModelFactory(pluginManager) {
         },
     }))
         .views(self => ({
+        /**
+         * #method
+         */
         // eslint-disable-next-line @typescript-eslint/no-explicit-any
         MiniControlsComponent() {
             return MiniControls_1.default;
         },
+        /**
+         * #method
+         */
         // eslint-disable-next-line @typescript-eslint/no-explicit-any
         HeaderComponent() {
             return Header_1.default;
         },
+        /**
+         * #getter
+         */
         get assemblyErrors() {
             const { assemblyManager } = (0, util_1.getSession)(self);
             const { assemblyNames } = self;
@@ -169,23 +245,41 @@ function stateModelFactory(pluginManager) {
                 .filter(f => !!f)
                 .join(', ');
         },
+        /**
+         * #getter
+         */
         get assembliesInitialized() {
             const { assemblyManager } = (0, util_1.getSession)(self);
             const { assemblyNames } = self;
             return assemblyNames.every(a => { var _a; return (_a = assemblyManager.get(a)) === null || _a === void 0 ? void 0 : _a.initialized; });
         },
+        /**
+         * #getter
+         */
         get initialized() {
             return self.volatileWidth !== undefined && this.assembliesInitialized;
         },
+        /**
+         * #getter
+         */
         get hasDisplayedRegions() {
             return self.displayedRegions.length > 0;
         },
+        /**
+         * #getter
+         */
         get isSearchDialogDisplayed() {
             return self.searchResults !== undefined;
         },
+        /**
+         * #getter
+         */
         get scaleBarHeight() {
             return exports.SCALE_BAR_HEIGHT + exports.RESIZE_HANDLE_HEIGHT;
         },
+        /**
+         * #getter
+         */
         get headerHeight() {
             if (self.hideHeader) {
                 return 0;
@@ -195,44 +289,77 @@ function stateModelFactory(pluginManager) {
             }
             return exports.HEADER_BAR_HEIGHT + exports.HEADER_OVERVIEW_HEIGHT;
         },
+        /**
+         * #getter
+         */
         get trackHeights() {
             return self.tracks
                 .map(t => t.displays[0].height)
                 .reduce((a, b) => a + b, 0);
         },
+        /**
+         * #getter
+         */
         get trackHeightsWithResizeHandles() {
             return this.trackHeights + self.tracks.length * exports.RESIZE_HANDLE_HEIGHT;
         },
+        /**
+         * #getter
+         */
         get height() {
             return (this.trackHeightsWithResizeHandles +
                 this.headerHeight +
                 this.scaleBarHeight);
         },
+        /**
+         * #getter
+         */
         get totalBp() {
             return self.displayedRegions.reduce((a, b) => a + b.end - b.start, 0);
         },
+        /**
+         * #getter
+         */
         get maxBpPerPx() {
             return this.totalBp / (self.width * 0.9);
         },
+        /**
+         * #getter
+         */
         get minBpPerPx() {
             return 1 / 50;
         },
+        /**
+         * #getter
+         */
         get error() {
             return self.volatileError || this.assemblyErrors;
         },
+        /**
+         * #getter
+         */
         get maxOffset() {
             // objectively determined to keep the linear genome on the main screen
             const leftPadding = 10;
             return this.displayedRegionsTotalPx - leftPadding;
         },
+        /**
+         * #getter
+         */
         get minOffset() {
             // objectively determined to keep the linear genome on the main screen
             const rightPadding = 30;
             return -self.width + rightPadding;
         },
+        /**
+         * #getter
+         */
         get displayedRegionsTotalPx() {
             return this.totalBp / self.bpPerPx;
         },
+        /**
+         * #method
+         */
         renderProps() {
             return {
                 ...(0, tracks_1.getParentRenderProps)(self),
@@ -240,6 +367,9 @@ function stateModelFactory(pluginManager) {
                 highResolutionScaling: (0, configuration_1.getConf)((0, util_1.getSession)(self), 'highResolutionScaling'),
             };
         },
+        /**
+         * #method
+         */
         searchScope(assemblyName) {
             return {
                 assemblyName,
@@ -247,9 +377,15 @@ function stateModelFactory(pluginManager) {
                 tracks: self.tracks,
             };
         },
+        /**
+         * #method
+         */
         getTrack(id) {
             return self.tracks.find(t => t.configuration.trackId === id);
         },
+        /**
+         * #method
+         */
         rankSearchResults(results) {
             // order of rank
             const openTrackIds = self.tracks.map(track => track.configuration.trackId);
@@ -260,7 +396,10 @@ function stateModelFactory(pluginManager) {
             });
             return results;
         },
-        // modifies view menu action onClick to apply to all tracks of same type
+        /**
+         * #method
+         * modifies view menu action onClick to apply to all tracks of same type
+         */
         rewriteOnClicks(trackType, viewMenuActions) {
             viewMenuActions.forEach(action => {
                 // go to lowest level menu
@@ -279,6 +418,9 @@ function stateModelFactory(pluginManager) {
                 }
             });
         },
+        /**
+         * #getter
+         */
         get trackTypeActions() {
             const allActions = new Map();
             self.tracks.forEach(track => {
@@ -293,33 +435,60 @@ 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 = (0, util_1.clamp)(offsetPx, self.minOffset, self.maxOffset);
             self.offsetPx = newOffsetPx;
             return newOffsetPx;
         },
+        /**
+         * #action
+         */
         zoomTo(bpPerPx) {
             const newBpPerPx = (0, util_1.clamp)(bpPerPx, self.minBpPerPx, self.maxBpPerPx);
             if (newBpPerPx === self.bpPerPx) {
@@ -337,22 +506,37 @@ 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 = (0, mobx_state_tree_1.cast)(self.displayedRegions
                 .slice()
@@ -360,6 +544,9 @@ 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 = (0, mobx_state_tree_1.resolveIdentifier)(schema, (0, mobx_state_tree_1.getRoot)(self), trackId);
@@ -395,6 +582,9 @@ function stateModelFactory(pluginManager) {
             }
             return t[0];
         },
+        /**
+         * #action
+         */
         hideTrack(trackId) {
             const schema = pluginManager.pluggableConfigSchemaType('track');
             const conf = (0, mobx_state_tree_1.resolveIdentifier)(schema, (0, mobx_state_tree_1.getRoot)(self), trackId);
@@ -404,6 +594,9 @@ function stateModelFactory(pluginManager) {
         },
     }))
         .actions(self => ({
+        /**
+         * #action
+         */
         moveTrack(movingId, targetId) {
             const oldIndex = self.tracks.findIndex(track => track.id === movingId);
             if (oldIndex === -1) {
@@ -417,6 +610,9 @@ function stateModelFactory(pluginManager) {
             self.tracks.splice(oldIndex, 1);
             self.tracks.splice(newIndex, 0, track);
         },
+        /**
+         * #action
+         */
         closeView() {
             const parent = (0, util_1.getContainingView)(self);
             if (parent) {
@@ -430,6 +626,9 @@ function stateModelFactory(pluginManager) {
                 (0, util_1.getSession)(self).removeView(self);
             }
         },
+        /**
+         * #action
+         */
         toggleTrack(trackId) {
             // if we have any tracks with that configuration, turn them off
             const hiddenCount = self.hideTrack(trackId);
@@ -438,18 +637,30 @@ 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 = (0, mobx_state_tree_1.cast)(regions);
             self.zoomTo(self.bpPerPx);
         },
+        /**
+         * #action
+         */
         activateTrackSelector() {
             if (self.trackSelectorType === 'hierarchical') {
                 const session = (0, util_1.getSession)(self);
@@ -462,6 +673,7 @@ 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
          *
@@ -483,38 +695,51 @@ 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 = (0, util_1.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) {
@@ -526,15 +751,24 @@ 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.displayedRegions.clear();
             self.tracks.clear();
             // it is necessary to run these after setting displayed regions empty
             // or else model.offsetPx gets set to Infinity and breaks
@@ -542,6 +776,10 @@ 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 (0, LinearGenomeViewSvg_1.renderToSvg)(self, opts);
@@ -551,6 +789,10 @@ function stateModelFactory(pluginManager) {
     }))
         .actions(self => {
         let cancelLastAnimation = () => { };
+        /**
+         * #action
+         * perform animated slide
+         */
         function slide(viewWidths) {
             const [animate, cancelAnimation] = (0, util_1.springAnimate)(self.offsetPx, self.offsetPx + self.width * viewWidths, self.scrollTo);
             cancelLastAnimation();
@@ -561,6 +803,10 @@ function stateModelFactory(pluginManager) {
     })
         .actions(self => {
         let cancelLastAnimation = () => { };
+        /**
+         * #action
+         * perform animated zoom
+         */
         function zoom(targetBpPerPx) {
             self.zoomTo(self.bpPerPx);
             if (
@@ -582,17 +828,30 @@ 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 } = (0, util_1.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
                 ? (0, util_1.measureText)(self.displayedRegions[0].refName, 12) + 15
@@ -600,6 +859,10 @@ function stateModelFactory(pluginManager) {
         },
     }))
         .views(self => ({
+        /**
+         * #method
+         * return the view menu items
+         */
         menuItems() {
             const { canShowCytobands, showCytobands } = self;
             const session = (0, util_1.getSession)(self);
@@ -647,59 +910,57 @@ function stateModelFactory(pluginManager) {
                     icon: SyncAlt_1.default,
                     onClick: self.horizontallyFlip,
                 },
-                { type: 'divider' },
-                {
-                    label: 'Show all regions in assembly',
-                    icon: Visibility_1.default,
-                    onClick: self.showAllRegionsInAssembly,
-                },
-                {
-                    label: 'Show center line',
-                    icon: Visibility_1.default,
-                    type: 'checkbox',
-                    checked: self.showCenterLine,
-                    onClick: self.toggleCenterLine,
-                },
-                {
-                    label: 'Show header',
-                    icon: Visibility_1.default,
-                    type: 'checkbox',
-                    checked: !self.hideHeader,
-                    onClick: self.toggleHeader,
-                },
                 {
-                    label: 'Show header overview',
+                    label: 'Show...',
                     icon: Visibility_1.default,
-                    type: 'checkbox',
-                    checked: !self.hideHeaderOverview,
-                    onClick: self.toggleHeaderOverview,
-                    disabled: self.hideHeader,
-                },
-                {
-                    label: 'Show no tracks active button',
-                    icon: Visibility_1.default,
-                    type: 'checkbox',
-                    checked: !self.hideNoTracksActive,
-                    onClick: self.toggleNoTracksActive,
-                },
-                {
-                    label: 'Show guidelines',
-                    icon: Visibility_1.default,
-                    type: 'checkbox',
-                    checked: self.showGridlines,
-                    onClick: self.toggleShowGridlines,
-                },
-                ...(canShowCytobands
-                    ? [
+                    subMenu: [
                         {
-                            label: 'Show ideogram',
-                            icon: Visibility_1.default,
+                            label: 'Show all regions in assembly',
+                            onClick: self.showAllRegionsInAssembly,
+                        },
+                        {
+                            label: 'Show center line',
                             type: 'checkbox',
-                            checked: self.showCytobands,
-                            onClick: () => self.setShowCytobands(!showCytobands),
+                            checked: self.showCenterLine,
+                            onClick: self.toggleCenterLine,
                         },
-                    ]
-                    : []),
+                        {
+                            label: 'Show header',
+                            type: 'checkbox',
+                            checked: !self.hideHeader,
+                            onClick: self.toggleHeader,
+                        },
+                        {
+                            label: 'Show header overview',
+                            type: 'checkbox',
+                            checked: !self.hideHeaderOverview,
+                            onClick: self.toggleHeaderOverview,
+                            disabled: self.hideHeader,
+                        },
+                        {
+                            label: 'Show no tracks active button',
+                            type: 'checkbox',
+                            checked: !self.hideNoTracksActive,
+                            onClick: self.toggleNoTracksActive,
+                        },
+                        {
+                            label: 'Show guidelines',
+                            type: 'checkbox',
+                            checked: self.showGridlines,
+                            onClick: self.toggleShowGridlines,
+                        },
+                        ...(canShowCytobands
+                            ? [
+                                {
+                                    label: 'Show ideogram',
+                                    type: 'checkbox',
+                                    checked: self.showCytobands,
+                                    onClick: () => self.setShowCytobands(!showCytobands),
+                                },
+                            ]
+                            : []),
+                    ],
+                },
                 {
                     label: 'Track labels',
                     icon: Label_1.default,
@@ -742,6 +1003,15 @@ 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 = (0, calculateStaticBlocks_1.default)(self);
                 const sret = JSON.stringify(ret);
@@ -751,27 +1021,48 @@ 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 (0, calculateDynamicBlocks_1.default)(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;
@@ -786,6 +1077,7 @@ 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
          *
@@ -795,7 +1087,14 @@ function stateModelFactory(pluginManager) {
         moveTo(start, end) {
             (0, Base1DUtils_1.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 } = (0, util_1.getSession)(self);
             const { isValidRefName } = assemblyManager;
@@ -805,6 +1104,9 @@ 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 {
@@ -825,9 +1127,9 @@ 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`);
@@ -840,7 +1142,7 @@ 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}`);
                 }
@@ -849,7 +1151,7 @@ function stateModelFactory(pluginManager) {
                     assemblyName: asmName,
                     parentRegion,
                 };
-            });
+            }));
             if (locations.length === 1) {
                 const loc = locations[0];
                 self.setDisplayedRegions([
@@ -870,6 +1172,7 @@ 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
@@ -878,11 +1181,14 @@ 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;
@@ -947,31 +1253,31 @@ function stateModelFactory(pluginManager) {
                         this.moveTo({ index, offset: f.reversed ? f.end - e : s - f.start }, { index, offset: f.reversed ? f.end - s : e - f.start });
                         return;
                     }
-                    let locationIndex = 0;
-                    let locationStart = 0;
-                    let locationEnd = 0;
-                    for (locationIndex; locationIndex < locations.length; locationIndex++) {
-                        const location = locations[locationIndex];
-                        const region = self.displayedRegions[index + locationIndex];
-                        locationStart = location.start || region.start;
-                        locationEnd = location.end || region.end;
+                    let idx = 0;
+                    let start = 0;
+                    let end = 0;
+                    for (idx; idx < locations.length; idx++) {
+                        const location = locations[idx];
+                        const region = self.displayedRegions[index + idx];
+                        start = location.start || region.start;
+                        end = location.end || region.end;
                         if (location.refName !== region.refName) {
                             throw new Error(`Entered location ${(0, util_1.assembleLocString)(location)} does not match with displayed regions`);
                         }
                     }
-                    locationIndex -= 1;
+                    idx -= 1;
                     const startDisplayedRegion = self.displayedRegions[index];
-                    const endDisplayedRegion = self.displayedRegions[index + locationIndex];
+                    const endDisplayedRegion = self.displayedRegions[index + idx];
                     this.moveTo({
                         index,
                         offset: startDisplayedRegion.reversed
                             ? startDisplayedRegion.end - e
                             : s - startDisplayedRegion.start,
                     }, {
-                        index: index + locationIndex,
+                        index: index + idx,
                         offset: endDisplayedRegion.reversed
-                            ? endDisplayedRegion.end - locationStart
-                            : locationEnd - endDisplayedRegion.start,
+                            ? endDisplayedRegion.end - start
+                            : end - endDisplayedRegion.start,
                     });
                     return;
                 }
@@ -984,6 +1290,9 @@ function stateModelFactory(pluginManager) {
         },
     }))
         .views(self => ({
+        /**
+         * #method
+         */
         rubberBandMenuItems() {
             return [
                 {
@@ -1001,10 +1310,14 @@ function stateModelFactory(pluginManager) {
                 },
             ];
         },
+        /**
+         * #method
+         */
         bpToPx({ refName, coord, regionNumber, }) {
             return (0, Base1DUtils_1.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
@@ -1021,9 +1334,15 @@ function stateModelFactory(pluginManager) {
                 self.scrollTo(Math.round(centerPx.offsetPx - self.width / 2));
             }
         },
+        /**
+         * #method
+         */
         pxToBp(px) {
             return (0, Base1DUtils_1.pxToBp)(self, px);
         },
+        /**
+         * #getter
+         */
         get centerLineInfo() {
             return self.displayedRegions.length
                 ? this.pxToBp(self.width / 2)