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

package/src/LinearGenomeView/index.tsx

@@ -59,6 +59,7 @@ import Header from './components/Header'
 import ZoomControls from './components/ZoomControls'
 import LinearGenomeView from './components/LinearGenomeView'
 
+// lazies
 const SequenceSearchDialog = lazy(
   () => import('./components/SequenceSearchDialog'),
 )
@@ -78,6 +79,8 @@ export interface BpOffset {
 export interface ExportSvgOptions {
   rasterizeLayers?: boolean
   filename?: string
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  Wrapper?: React.FC<any>
 }
 
 function calculateVisibleLocStrings(contentBlocks: BaseBlock[]) {
@@ -85,7 +88,7 @@ function calculateVisibleLocStrings(contentBlocks: BaseBlock[]) {
     return ''
   }
   const isSingleAssemblyName = contentBlocks.every(
-    block => block.assemblyName === contentBlocks[0].assemblyName,
+    b => b.assemblyName === contentBlocks[0].assemblyName,
   )
   const locs = contentBlocks.map(block =>
     assembleLocString({
@@ -119,41 +122,110 @@ function localStorageGetItem(item: string) {
     : undefined
 }
 
+/**
+ * #stateModel LinearGenomeView
+ */
 export function stateModelFactory(pluginManager: PluginManager) {
   return types
     .compose(
       BaseViewModel,
       types.model('LinearGenomeView', {
+        /**
+         * #property
+         */
         id: ElementId,
-        type: types.literal('LinearGenomeView'),
+
+        /**
+         * #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: types.literal('LinearGenomeView') as unknown as string,
+
+        /**
+         * #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,
       }),
     )
@@ -178,6 +250,9 @@ export function stateModelFactory(pluginManager: PluginManager) {
       seqDialogDisplayed: false,
     }))
     .views(self => ({
+      /**
+       * #getter
+       */
       get width(): number {
         if (self.volatileWidth === undefined) {
           throw new Error(
@@ -186,10 +261,16 @@ export function stateModelFactory(pluginManager: PluginManager) {
         }
         return self.volatileWidth
       },
+      /**
+       * #getter
+       */
       get interRegionPaddingWidth() {
         return INTER_REGION_PADDING_WIDTH
       },
 
+      /**
+       * #getter
+       */
       get assemblyNames() {
         return [
           ...new Set(self.displayedRegions.map(region => region.assemblyName)),
@@ -197,16 +278,25 @@ export function stateModelFactory(pluginManager: PluginManager) {
       },
     }))
     .views(self => ({
+      /**
+       * #method
+       */
       // eslint-disable-next-line @typescript-eslint/no-explicit-any
       MiniControlsComponent(): React.FC<any> {
         return MiniControls
       },
 
+      /**
+       * #method
+       */
       // eslint-disable-next-line @typescript-eslint/no-explicit-any
       HeaderComponent(): React.FC<any> {
         return Header
       },
 
+      /**
+       * #getter
+       */
       get assemblyErrors() {
         const { assemblyManager } = getSession(self)
         const { assemblyNames } = self
@@ -216,23 +306,46 @@ export function stateModelFactory(pluginManager: PluginManager) {
           .join(', ')
       },
 
+      /**
+       * #getter
+       */
       get assembliesInitialized() {
         const { assemblyManager } = getSession(self)
         const { assemblyNames } = self
         return assemblyNames.every(a => assemblyManager.get(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 SCALE_BAR_HEIGHT + RESIZE_HANDLE_HEIGHT
       },
+
+      /**
+       * #getter
+       */
       get headerHeight() {
         if (self.hideHeader) {
           return 0
@@ -242,15 +355,26 @@ export function stateModelFactory(pluginManager: PluginManager) {
         }
         return HEADER_BAR_HEIGHT + 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 * RESIZE_HANDLE_HEIGHT
       },
+
+      /**
+       * #getter
+       */
       get height() {
         return (
           this.trackHeightsWithResizeHandles +
@@ -258,38 +382,63 @@ export function stateModelFactory(pluginManager: PluginManager) {
           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 {
           ...getParentRenderProps(self),
@@ -301,6 +450,9 @@ export function stateModelFactory(pluginManager: PluginManager) {
         }
       },
 
+      /**
+       * #method
+       */
       searchScope(assemblyName: string) {
         return {
           assemblyName,
@@ -309,10 +461,16 @@ export function stateModelFactory(pluginManager: PluginManager) {
         }
       },
 
+      /**
+       * #method
+       */
       getTrack(id: string) {
         return self.tracks.find(t => t.configuration.trackId === id)
       },
 
+      /**
+       * #method
+       */
       rankSearchResults(results: BaseResult[]) {
         // order of rank
         const openTrackIds = self.tracks.map(
@@ -326,7 +484,10 @@ export function stateModelFactory(pluginManager: 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: string, viewMenuActions: MenuItem[]) {
         viewMenuActions.forEach(action => {
           // go to lowest level menu
@@ -345,7 +506,9 @@ export function stateModelFactory(pluginManager: PluginManager) {
           }
         })
       },
-
+      /**
+       * #getter
+       */
       get trackTypeActions() {
         const allActions: Map<string, MenuItem[]> = new Map()
         self.tracks.forEach(track => {
@@ -361,37 +524,61 @@ export function stateModelFactory(pluginManager: PluginManager) {
       },
     }))
     .actions(self => ({
+      /**
+       * #action
+       */
       setShowCytobands(flag: boolean) {
         self.showCytobandsSetting = flag
         localStorage.setItem('lgv-showCytobands', `${+flag}`)
       },
+      /**
+       * #action
+       */
       setWidth(newWidth: number) {
         self.volatileWidth = newWidth
       },
+      /**
+       * #action
+       */
       setError(error: Error | undefined) {
         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: number) {
         const newOffsetPx = clamp(offsetPx, self.minOffset, self.maxOffset)
         self.offsetPx = newOffsetPx
         return newOffsetPx
       },
 
+      /**
+       * #action
+       */
       zoomTo(bpPerPx: number) {
         const newBpPerPx = clamp(bpPerPx, self.minBpPerPx, self.maxBpPerPx)
         if (newBpPerPx === self.bpPerPx) {
@@ -416,26 +603,41 @@ export function stateModelFactory(pluginManager: PluginManager) {
         return newBpPerPx
       },
 
+      /**
+       * #action
+       * sets offsets used in the get sequence dialog
+       */
       setOffsets(left?: BpOffset, right?: BpOffset) {
-        // sets offsets used in the get sequence dialog
         self.leftOffset = left
         self.rightOffset = right
       },
 
+      /**
+       * #action
+       */
       setSearchResults(results?: BaseResult[], query?: string) {
         self.searchResults = results
         self.searchQuery = query
       },
 
+      /**
+       * #action
+       */
       setGetSequenceDialogOpen(open: boolean) {
         self.seqDialogDisplayed = open
       },
 
+      /**
+       * #action
+       */
       setNewView(bpPerPx: number, offsetPx: number) {
         this.zoomTo(bpPerPx)
         this.scrollTo(offsetPx)
       },
 
+      /**
+       * #action
+       */
       horizontallyFlip() {
         self.displayedRegions = cast(
           self.displayedRegions
@@ -446,6 +648,9 @@ export function stateModelFactory(pluginManager: PluginManager) {
         this.scrollTo(self.totalBp / self.bpPerPx - self.offsetPx - self.width)
       },
 
+      /**
+       * #action
+       */
       showTrack(
         trackId: string,
         initialSnapshot = {},
@@ -490,7 +695,9 @@ export function stateModelFactory(pluginManager: PluginManager) {
         }
         return t[0]
       },
-
+      /**
+       * #action
+       */
       hideTrack(trackId: string) {
         const schema = pluginManager.pluggableConfigSchemaType('track')
         const conf = resolveIdentifier(schema, getRoot(self), trackId)
@@ -500,6 +707,9 @@ export function stateModelFactory(pluginManager: PluginManager) {
       },
     }))
     .actions(self => ({
+      /**
+       * #action
+       */
       moveTrack(movingId: string, targetId: string) {
         const oldIndex = self.tracks.findIndex(track => track.id === movingId)
         if (oldIndex === -1) {
@@ -514,6 +724,9 @@ export function stateModelFactory(pluginManager: PluginManager) {
         self.tracks.splice(newIndex, 0, track)
       },
 
+      /**
+       * #action
+       */
       closeView() {
         const parent = getContainingView(self)
         if (parent) {
@@ -527,6 +740,9 @@ export function stateModelFactory(pluginManager: PluginManager) {
         }
       },
 
+      /**
+       * #action
+       */
       toggleTrack(trackId: string) {
         // if we have any tracks with that configuration, turn them off
         const hiddenCount = self.hideTrack(trackId)
@@ -536,21 +752,33 @@ export function stateModelFactory(pluginManager: PluginManager) {
         }
       },
 
+      /**
+       * #action
+       */
       setTrackLabels(setting: 'overlapping' | 'offset' | 'hidden') {
         self.trackLabels = setting
         localStorage.setItem('lgv-trackLabels', setting)
       },
 
+      /**
+       * #action
+       */
       toggleCenterLine() {
         self.showCenterLine = !self.showCenterLine
         localStorage.setItem('lgv-showCenterLine', `${+self.showCenterLine}`)
       },
 
+      /**
+       * #action
+       */
       setDisplayedRegions(regions: Region[]) {
         self.displayedRegions = cast(regions)
         self.zoomTo(self.bpPerPx)
       },
 
+      /**
+       * #action
+       */
       activateTrackSelector() {
         if (self.trackSelectorType === 'hierarchical') {
           const session = getSession(self)
@@ -568,6 +796,7 @@ export function stateModelFactory(pluginManager: PluginManager) {
       },
 
       /**
+       * #method
        * Helper method for the fetchSequence.
        * Retrieves the corresponding regions that were selected by the rubberband
        *
@@ -592,11 +821,17 @@ export function stateModelFactory(pluginManager: PluginManager) {
         }))
       },
 
-      // 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: Function) {
         self.afterDisplayedRegionsSetCallbacks.push(cb)
       },
 
+      /**
+       * #action
+       */
       horizontalScroll(distance: number) {
         const oldOffsetPx = self.offsetPx
         // newOffsetPx is the actual offset after the scroll is clamped
@@ -604,34 +839,38 @@ export function stateModelFactory(pluginManager: PluginManager) {
         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?: string) {
         const session = getSession(self)
         const { assemblyManager } = session
         if (!assemblyName) {
-          const assemblyNames = [
-            ...new Set(
-              self.displayedRegions.map(region => region.assemblyName),
-            ),
-          ]
-          if (assemblyNames.length > 1) {
+          const names = new Set(self.displayedRegions.map(r => r.assemblyName))
+          if (names.size > 1) {
             session.notify(
-              `Can't perform this with multiple assemblies currently`,
+              `Can't perform operation with multiple assemblies currently`,
             )
             return
           }
-
-          ;[assemblyName] = assemblyNames
+          ;[assemblyName] = [...names]
         }
         const assembly = assemblyManager.get(assemblyName)
         if (assembly) {
@@ -644,16 +883,26 @@ export function stateModelFactory(pluginManager: PluginManager) {
         }
       },
 
+      /**
+       * #action
+       */
       setDraggingTrackId(idx?: string) {
         self.draggingTrackId = idx
       },
 
+      /**
+       * #action
+       */
       setScaleFactor(factor: number) {
         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
@@ -661,6 +910,11 @@ export function stateModelFactory(pluginManager: PluginManager) {
         self.scrollTo(0)
         self.zoomTo(10)
       },
+
+      /**
+       * #action
+       * creates an svg export and save using FileSaver
+       */
       async exportSvg(opts: ExportSvgOptions = {}) {
         // eslint-disable-next-line @typescript-eslint/no-explicit-any
         const html = await renderToSvg(self as any, opts)
@@ -671,6 +925,10 @@ export function stateModelFactory(pluginManager: PluginManager) {
     .actions(self => {
       let cancelLastAnimation = () => {}
 
+      /**
+       * #action
+       * perform animated slide
+       */
       function slide(viewWidths: number) {
         const [animate, cancelAnimation] = springAnimate(
           self.offsetPx,
@@ -687,6 +945,10 @@ export function stateModelFactory(pluginManager: PluginManager) {
     .actions(self => {
       let cancelLastAnimation = () => {}
 
+      /**
+       * #action
+       * perform animated zoom
+       */
       function zoom(targetBpPerPx: number) {
         self.zoomTo(self.bpPerPx)
         if (
@@ -715,20 +977,32 @@ export function stateModelFactory(pluginManager: 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 => assemblyManager.get(asm)?.cytobands?.length,
+        return self.assemblyNames.some(
+          a => assemblyManager.get(a)?.cytobands?.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
@@ -736,6 +1010,10 @@ export function stateModelFactory(pluginManager: PluginManager) {
       },
     }))
     .views(self => ({
+      /**
+       * #method
+       * return the view menu items
+       */
       menuItems(): MenuItem[] {
         const { canShowCytobands, showCytobands } = self
         const session = getSession(self)
@@ -783,59 +1061,57 @@ export function stateModelFactory(pluginManager: PluginManager) {
             icon: SyncAltIcon,
             onClick: self.horizontallyFlip,
           },
-          { type: 'divider' },
-          {
-            label: 'Show all regions in assembly',
-            icon: VisibilityIcon,
-            onClick: self.showAllRegionsInAssembly,
-          },
-          {
-            label: 'Show center line',
-            icon: VisibilityIcon,
-            type: 'checkbox',
-            checked: self.showCenterLine,
-            onClick: self.toggleCenterLine,
-          },
           {
-            label: 'Show header',
+            label: 'Show...',
             icon: VisibilityIcon,
-            type: 'checkbox',
-            checked: !self.hideHeader,
-            onClick: self.toggleHeader,
-          },
-          {
-            label: 'Show header overview',
-            icon: VisibilityIcon,
-            type: 'checkbox',
-            checked: !self.hideHeaderOverview,
-            onClick: self.toggleHeaderOverview,
-            disabled: self.hideHeader,
-          },
-          {
-            label: 'Show no tracks active button',
-            icon: VisibilityIcon,
-            type: 'checkbox',
-            checked: !self.hideNoTracksActive,
-            onClick: self.toggleNoTracksActive,
-          },
-          {
-            label: 'Show guidelines',
-            icon: VisibilityIcon,
-            type: 'checkbox',
-            checked: self.showGridlines,
-            onClick: self.toggleShowGridlines,
+            subMenu: [
+              {
+                label: 'Show all regions in assembly',
+                onClick: self.showAllRegionsInAssembly,
+              },
+              {
+                label: 'Show center line',
+                type: 'checkbox',
+                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' as const,
+                      checked: self.showCytobands,
+                      onClick: () => self.setShowCytobands(!showCytobands),
+                    },
+                  ]
+                : []),
+            ],
           },
-          ...(canShowCytobands
-            ? [
-                {
-                  label: 'Show ideogram',
-                  icon: VisibilityIcon,
-                  type: 'checkbox' as const,
-                  checked: self.showCytobands,
-                  onClick: () => self.setShowCytobands(!showCytobands),
-                },
-              ]
-            : []),
           {
             label: 'Track labels',
             icon: LabelIcon,
@@ -883,6 +1159,15 @@ export function stateModelFactory(pluginManager: PluginManager) {
       let currentlyCalculatedStaticBlocks: BlockSet | undefined
       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)
@@ -892,33 +1177,58 @@ export function stateModelFactory(pluginManager: PluginManager) {
           }
           return currentlyCalculatedStaticBlocks as BlockSet
         },
-
+        /**
+         * #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),
+              } as BaseBlock),
+          )
         },
+
+        /**
+         * #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: BlockSet) {
         self.coarseDynamicBlocks = blocks.contentBlocks
         self.coarseTotalBp = blocks.totalBp
       },
+
       afterAttach() {
         addDisposer(
           self,
@@ -935,6 +1245,7 @@ export function stateModelFactory(pluginManager: 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
        *
@@ -945,7 +1256,14 @@ export function stateModelFactory(pluginManager: PluginManager) {
         moveTo(self, start, end)
       },
 
-      navToLocString(locString: string, optAssemblyName?: string) {
+      /**
+       * #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: string, optAssemblyName?: string) {
         const { assemblyNames } = self
         const { assemblyManager } = getSession(self)
         const { isValidRefName } = assemblyManager
@@ -956,6 +1274,10 @@ export function stateModelFactory(pluginManager: PluginManager) {
           .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 {
@@ -981,34 +1303,38 @@ export function stateModelFactory(pluginManager: PluginManager) {
           }
         }
 
-        const locations = parsedLocStrings?.map(region => {
-          const asmName = region.assemblyName || assemblyName
-          const asm = assemblyManager.get(asmName)
-          const { refName } = region
-          if (!asm) {
-            throw new Error(`assembly ${asmName} not found`)
-          }
-          const { regions } = asm
-          if (!regions) {
-            throw new Error(`regions not loaded yet for ${asmName}`)
-          }
-          const canonicalRefName = asm.getCanonicalRefName(region.refName)
-          if (!canonicalRefName) {
-            throw new Error(`Could not find refName ${refName} in ${asm.name}`)
-          }
-          const parentRegion = regions.find(
-            region => region.refName === canonicalRefName,
-          )
-          if (!parentRegion) {
-            throw new Error(`Could not find refName ${refName} in ${asmName}`)
-          }
+        const locations = await Promise.all(
+          parsedLocStrings?.map(async region => {
+            const asmName = region.assemblyName || assemblyName
+            const asm = await assemblyManager.waitForAssembly(asmName)
+            const { refName } = region
+            if (!asm) {
+              throw new Error(`assembly ${asmName} not found`)
+            }
+            const { regions } = asm
+            if (!regions) {
+              throw new Error(`regions not loaded yet for ${asmName}`)
+            }
+            const canonicalRefName = asm.getCanonicalRefName(region.refName)
+            if (!canonicalRefName) {
+              throw new Error(
+                `Could not find refName ${refName} in ${asm.name}`,
+              )
+            }
+            const parentRegion = regions.find(
+              r => r.refName === canonicalRefName,
+            )
+            if (!parentRegion) {
+              throw new Error(`Could not find refName ${refName} in ${asmName}`)
+            }
 
-          return {
-            ...region,
-            assemblyName: asmName,
-            parentRegion,
-          }
-        })
+            return {
+              ...region,
+              assemblyName: asmName,
+              parentRegion,
+            }
+          }),
+        )
 
         if (locations.length === 1) {
           const loc = locations[0]
@@ -1032,6 +1358,7 @@ export function stateModelFactory(pluginManager: 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
@@ -1040,12 +1367,15 @@ export function stateModelFactory(pluginManager: 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: NavLocation) {
         this.navToMultiple([query])
       },
 
+      /**
+       * #action
+       */
       navToMultiple(locations: NavLocation[]) {
         const firstLocation = locations[0]
         let { refName } = firstLocation
@@ -1131,18 +1461,14 @@ export function stateModelFactory(pluginManager: PluginManager) {
               )
               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 ${assembleLocString(
@@ -1151,10 +1477,9 @@ export function stateModelFactory(pluginManager: PluginManager) {
                 )
               }
             }
-            locationIndex -= 1
+            idx -= 1
             const startDisplayedRegion = self.displayedRegions[index]
-            const endDisplayedRegion =
-              self.displayedRegions[index + locationIndex]
+            const endDisplayedRegion = self.displayedRegions[index + idx]
             this.moveTo(
               {
                 index,
@@ -1163,10 +1488,10 @@ export function stateModelFactory(pluginManager: PluginManager) {
                   : 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
@@ -1179,6 +1504,9 @@ export function stateModelFactory(pluginManager: PluginManager) {
       },
     }))
     .views(self => ({
+      /**
+       * #method
+       */
       rubberBandMenuItems(): MenuItem[] {
         return [
           {
@@ -1197,6 +1525,9 @@ export function stateModelFactory(pluginManager: PluginManager) {
         ]
       },
 
+      /**
+       * #method
+       */
       bpToPx({
         refName,
         coord,
@@ -1210,6 +1541,7 @@ export function stateModelFactory(pluginManager: PluginManager) {
       },
 
       /**
+       * #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
@@ -1227,10 +1559,16 @@ export function stateModelFactory(pluginManager: PluginManager) {
         }
       },
 
+      /**
+       * #method
+       */
       pxToBp(px: number) {
         return pxToBp(self, px)
       },
 
+      /**
+       * #getter
+       */
       get centerLineInfo() {
         return self.displayedRegions.length
           ? this.pxToBp(self.width / 2)