react-msaview 9.0.0 → 9.1.1

package/src/components/MSAViewer.tsx

@@ -1,12 +1,23 @@
-import React, { useEffect, useRef, useState } from 'react'
+import React, {
+  forwardRef,
+  useEffect,
+  useImperativeHandle,
+  useRef,
+  useState,
+} from 'react'
 
-import { createJBrowseTheme } from '@jbrowse/core/ui/theme'
 import useMeasure from '@jbrowse/core/util/useMeasure'
 import { destroy, isAlive } from '@jbrowse/mobx-state-tree'
 import { ThemeProvider } from '@mui/material/styles'
 import { compareStructural, reaction, when } from 'mobx'
 
 import MSAModelF from '../model.ts'
+import {
+  fileLocations,
+  resolveTheme,
+  viewerHighlights,
+  viewerSnapshot,
+} from '../viewerSnapshot.ts'
 import Loading from './Loading.tsx'
 
 import type { MsaViewModel } from '../model.ts'
@@ -30,16 +41,7 @@ import type {
 } from '../types.ts'
 import type { FileLocation as FileLocationType } from '@jbrowse/core/util/types'
 import type { ThemeOptions } from '@mui/material/styles'
-
-function resolveTheme(theme: MSAViewerProps['theme']) {
-  return createJBrowseTheme(
-    theme === 'dark'
-      ? { palette: { mode: 'dark' } }
-      : typeof theme === 'object'
-        ? theme
-        : undefined,
-  )
-}
+import type { ForwardedRef } from 'react'
 
 export interface MSAViewerProps {
   msa?: string
@@ -48,6 +50,12 @@ export interface MSAViewerProps {
   msaFilehandle?: FileLocationType
   treeFilehandle?: FileLocationType
   gffFilehandle?: FileLocationType
+  /** a URL the viewer fetches the alignment from; `msaFilehandle` wins */
+  msaUrl?: string
+  /** a URL the viewer fetches the Newick tree from; `treeFilehandle` wins */
+  treeUrl?: string
+  /** a URL the viewer fetches the GFF from; `gffFilehandle` wins */
+  gffUrl?: string
   /**
    * a scheme name from the built-in table, or `{map}`, a color per residue
    * letter that leaves every other letter uncolored
@@ -62,7 +70,10 @@ export interface MSAViewerProps {
    * hide columns at least this percent gaps (default 100, i.e. hide nothing)
    */
   allowedGappyness?: number
-  /** alignment columns (0-based) to highlight with a persistent overlay */
+  /**
+   * alignment columns, 1-based like `highlights`, drawn as one `{start, end}`
+   * highlight per run of adjacent columns
+   */
   highlightColumns?: number[]
   /**
    * labeled highlights in 1-based inclusive coordinates: `{start, end}` for
@@ -158,19 +169,12 @@ export interface MSAViewerProps {
   onSelectionChange?: (selection: MsaSelection | undefined) => void
   /**
    * the model the viewer built, for the model API; called again with the new
-   * model when msa, tree, msaFilehandle or treeFilehandle changes
+   * model when msa, tree, msaUrl, treeUrl, msaFilehandle or treeFilehandle
+   * changes
    */
   onModel?: (model: MsaViewModel) => void
 }
 
-function colorSchemeSnapshot(scheme: ColorScheme | undefined) {
-  return typeof scheme === 'string'
-    ? { colorSchemeName: scheme }
-    : scheme
-      ? { customColorScheme: scheme.map }
-      : {}
-}
-
 type DataSource = Pick<
   MSAViewerProps,
   'msa' | 'tree' | 'msaFilehandle' | 'treeFilehandle'
@@ -188,17 +192,22 @@ function sameSource(a: DataSource, b: DataSource) {
 /**
  * A new alignment or tree needs a new model, so the viewer remounts when one
  * of those props changes and keeps its model across every other change,
- * including a new annotation file.
+ * including a new annotation file. A `ref` holds the current model.
  */
-export default function MSAViewer(props: MSAViewerProps) {
-  const { msa, tree, msaFilehandle, treeFilehandle } = props
-  const source = { msa, tree, msaFilehandle, treeFilehandle }
-  const [shown, setShown] = useState({ source, generation: 0 })
-  if (!sameSource(shown.source, source)) {
-    setShown({ source, generation: shown.generation + 1 })
-  }
-  return <Viewer key={shown.generation} {...props} />
-}
+const MSAViewer = forwardRef<MsaViewModel, MSAViewerProps>(
+  function MSAViewer(props, ref) {
+    const resolved = { ...props, ...fileLocations(props) }
+    const { msa, tree, msaFilehandle, treeFilehandle } = resolved
+    const source = { msa, tree, msaFilehandle, treeFilehandle }
+    const [shown, setShown] = useState({ source, generation: 0 })
+    if (!sameSource(shown.source, source)) {
+      setShown({ source, generation: shown.generation + 1 })
+    }
+    return <Viewer key={shown.generation} modelRef={ref} {...resolved} />
+  },
+)
+
+export default MSAViewer
 
 function useModelReaction<
   K extends 'hoveredCell' | 'clickedCell' | 'viewport' | 'selection',
@@ -227,87 +236,237 @@ function useModelReaction<
   )
 }
 
-function Viewer({
-  msa,
-  tree,
-  gff,
-  msaFilehandle,
-  treeFilehandle,
-  gffFilehandle,
-  colorScheme,
-  height,
-  colWidth,
-  rowHeight,
-  allowedGappyness,
-  highlightColumns,
-  highlights,
-  features,
-  clades,
-  relativeTo,
-  columnTracks,
-  residueMappings,
-  rowData,
-  encodings,
-  rowPanels,
-  drawTree,
-  residueEncoding,
-  treeAreaWidth,
-  showBranchLen,
-  treeOrder,
-  treeRoot,
-  region,
-  selection,
-  hideHeader,
-  theme,
-  onCellHover,
-  onCellClick,
-  onViewportChange,
-  onSelectionChange,
-  onModel,
-}: MSAViewerProps) {
-  const [model] = useState(() =>
-    MSAModelF().create({
-      type: 'MsaView',
-      ...(msa || tree || gff || rowData
-        ? {
-            data: {
-              msa: msa ?? '',
-              tree: tree ?? '',
-              gff,
-              // the row table is stored as this JSON string, which is what a
-              // shared URL and the size limit already cover
-              ...(rowData ? { treeMetadata: JSON.stringify(rowData) } : {}),
-            },
-          }
-        : {}),
-      ...(msaFilehandle ? { msaFilehandle } : {}),
-      ...(treeFilehandle ? { treeFilehandle } : {}),
-      ...(gffFilehandle ? { gffFilehandle } : {}),
-      ...colorSchemeSnapshot(colorScheme),
-      ...(height ? { height } : {}),
-      ...(colWidth ? { colWidth } : {}),
-      ...(rowHeight ? { rowHeight } : {}),
-      ...(allowedGappyness !== undefined ? { allowedGappyness } : {}),
-      ...(highlightColumns ? { highlightColumns } : {}),
-      ...(highlights ? { highlights } : {}),
-      ...(features ? { features } : {}),
-      ...(selection ? { selection } : {}),
-      ...(clades ? { clades } : {}),
-      ...(relativeTo ? { relativeTo } : {}),
-      ...(columnTracks ? { columnTracks } : {}),
-      ...(residueMappings ? { residueMappings } : {}),
-      ...(encodings ? { encodings } : {}),
-      ...(rowPanels ? { rowPanels } : {}),
-      ...(drawTree !== undefined ? { drawTree } : {}),
-      ...(treeAreaWidth ? { treeAreaWidth } : {}),
-      ...(showBranchLen !== undefined ? { showBranchLen } : {}),
-      ...(treeOrder ? { treeOrder } : {}),
-      ...(treeRoot ? { treeRoot } : {}),
-      ...(residueEncoding !== undefined
-        ? { bgColor: residueEncoding === 'fill' }
-        : {}),
+interface SyncedProp {
+  read: (props: MSAViewerProps) => unknown
+  apply: (model: MsaViewModel, value: unknown, props: MSAViewerProps) => void
+  inSnapshot?: boolean
+}
+
+function synced<T>(
+  read: (props: MSAViewerProps) => T,
+  apply: (model: MsaViewModel, value: T, props: MSAViewerProps) => void,
+  { inSnapshot = false } = {},
+): SyncedProp {
+  return {
+    read,
+    apply: apply as SyncedProp['apply'],
+    inSnapshot,
+  }
+}
+
+function ifSet<T>(set: (model: MsaViewModel, value: T) => void) {
+  return (model: MsaViewModel, value: T | undefined) => {
+    if (value !== undefined) {
+      set(model, value)
+    }
+  }
+}
+
+/**
+ * How each prop reaches the mounted model. `inSnapshot` marks a prop the
+ * snapshot already applied, so only a later change reaches its setter.
+ */
+const syncedProps = [
+  synced(
+    p => p.height,
+    ifSet((m, v) => {
+      m.setHeight(v)
     }),
-  )
+  ),
+  synced(
+    p => p.colWidth,
+    ifSet((m, v) => {
+      m.setColWidth(v)
+    }),
+  ),
+  synced(
+    p => p.rowHeight,
+    ifSet((m, v) => {
+      m.setRowHeight(v)
+    }),
+  ),
+  synced(
+    p => p.allowedGappyness,
+    ifSet((m, v) => {
+      m.setAllowedGappyness(v)
+    }),
+  ),
+  synced(
+    p => p.drawTree,
+    ifSet((m, v) => {
+      m.setDrawTree(v)
+    }),
+  ),
+  synced(
+    p => p.treeAreaWidth,
+    ifSet((m, v) => {
+      m.setTreeAreaWidth(v)
+    }),
+  ),
+  synced(
+    p => p.showBranchLen,
+    ifSet((m, v) => {
+      m.setShowBranchLen(v)
+    }),
+  ),
+  synced(
+    p => p.treeOrder,
+    ifSet((m, v) => {
+      m.setTreeOrder(v)
+    }),
+  ),
+  synced(
+    p => p.residueEncoding,
+    ifSet((m, v) => {
+      m.setBgColor(v === 'fill')
+    }),
+  ),
+  synced(
+    p => !!p.hideHeader,
+    (m, v) => {
+      m.setHideHeader(v)
+    },
+  ),
+  synced(
+    p => p.relativeTo,
+    (m, v) => {
+      m.drawRelativeTo(v)
+    },
+  ),
+  synced(
+    p => p.gffFilehandle,
+    (m, location, { gff }) => {
+      if (location) {
+        m.setGFFFilehandle(location)
+      } else {
+        m.setGFF(gff)
+      }
+    },
+    { inSnapshot: true },
+  ),
+  synced(
+    p => p.gff,
+    (m, v) => {
+      m.setGFF(v)
+    },
+    { inSnapshot: true },
+  ),
+  synced(
+    p => p.colorScheme,
+    (m, scheme) => {
+      if (typeof scheme === 'string') {
+        m.setColorSchemeName(scheme)
+      } else if (scheme) {
+        m.setCustomColorScheme(scheme.map)
+      }
+    },
+  ),
+  synced(viewerHighlights, (m, v) => {
+    m.setHighlights(v)
+  }),
+  synced(
+    p => p.features ?? [],
+    (m, v) => {
+      m.setFeatures(v)
+    },
+  ),
+  synced(
+    p => p.selection,
+    (m, v) => {
+      m.setSelection(v)
+    },
+  ),
+  synced(
+    p => p.treeRoot,
+    (m, v) => {
+      m.setTreeRoot(v)
+    },
+  ),
+  synced(
+    p => p.clades ?? [],
+    (m, v) => {
+      m.setClades(v)
+    },
+  ),
+  synced(
+    p => p.columnTracks ?? [],
+    (m, v) => {
+      m.setColumnTracks(v)
+    },
+  ),
+  synced(
+    p => p.residueMappings ?? [],
+    (m, v) => {
+      m.setResidueMappings(v)
+    },
+  ),
+  synced(
+    p => p.rowData,
+    (m, table) => {
+      if (table && Object.keys(table).length) {
+        m.setRowData(table)
+      }
+    },
+  ),
+  synced(
+    p => p.encodings ?? [],
+    (m, v) => {
+      m.setEncodings(v)
+    },
+  ),
+  synced(
+    p => p.rowPanels ?? [],
+    (m, v) => {
+      m.setRowPanels(v)
+    },
+  ),
+]
+
+/**
+ * Applies each prop whose content changed since the last render. Comparing
+ * JSON keys lets a host pass a freshly computed array every render, and
+ * applying only a changed prop keeps a change made inside the viewer across
+ * the host's next render. The model receives a parsed copy, never the host's
+ * own object.
+ */
+function useSyncedProps(model: MsaViewModel, props: MSAViewerProps) {
+  const applied = useRef<string[] | undefined>(undefined)
+  useEffect(() => {
+    const keys = syncedProps.map(({ read }) =>
+      JSON.stringify(read(props) ?? null),
+    )
+    applied.current ??= syncedProps.map(({ inSnapshot }, i) =>
+      inSnapshot ? keys[i]! : '',
+    )
+    const last = applied.current
+    syncedProps.forEach(({ apply }, i) => {
+      const key = keys[i]!
+      if (last[i] !== key) {
+        last[i] = key
+        apply(model, JSON.parse(key) ?? undefined, props)
+      }
+    })
+  })
+}
+
+function Viewer({
+  modelRef,
+  ...props
+}: MSAViewerProps & { modelRef: ForwardedRef<MsaViewModel> }) {
+  const {
+    region,
+    theme,
+    onCellHover,
+    onCellClick,
+    onViewportChange,
+    onSelectionChange,
+    onModel,
+  } = props
+  const [model] = useState(() => {
+    const model = MSAModelF().create(viewerSnapshot(props))
+    model.setImportForm(false)
+    return model
+  })
 
   const destroyTimer = useRef<ReturnType<typeof setTimeout> | undefined>(
     undefined,
@@ -320,144 +479,7 @@ function Viewer({
     }
   }, [model, width])
 
-  // Each effect depends only on its own prop, so a change made inside the
-  // viewer survives the host's next render.
-  useEffect(() => {
-    if (height !== undefined) {
-      model.setHeight(height)
-    }
-  }, [model, height])
-  useEffect(() => {
-    if (colWidth !== undefined) {
-      model.setColWidth(colWidth)
-    }
-  }, [model, colWidth])
-  useEffect(() => {
-    if (rowHeight !== undefined) {
-      model.setRowHeight(rowHeight)
-    }
-  }, [model, rowHeight])
-  useEffect(() => {
-    if (allowedGappyness !== undefined) {
-      model.setAllowedGappyness(allowedGappyness)
-    }
-  }, [model, allowedGappyness])
-  useEffect(() => {
-    if (drawTree !== undefined) {
-      model.setDrawTree(drawTree)
-    }
-  }, [model, drawTree])
-  useEffect(() => {
-    if (treeAreaWidth !== undefined) {
-      model.setTreeAreaWidth(treeAreaWidth)
-    }
-  }, [model, treeAreaWidth])
-  useEffect(() => {
-    if (showBranchLen !== undefined) {
-      model.setShowBranchLen(showBranchLen)
-    }
-  }, [model, showBranchLen])
-  useEffect(() => {
-    if (treeOrder !== undefined) {
-      model.setTreeOrder(treeOrder)
-    }
-  }, [model, treeOrder])
-  useEffect(() => {
-    if (residueEncoding !== undefined) {
-      model.setBgColor(residueEncoding === 'fill')
-    }
-  }, [model, residueEncoding])
-  useEffect(() => {
-    model.setHideHeader(!!hideHeader)
-  }, [model, hideHeader])
-  // unguarded, so removing the prop turns the reference diff off
-  useEffect(() => {
-    model.drawRelativeTo(relativeTo)
-  }, [model, relativeTo])
-
-  // The snapshot already holds the first gff and gffFilehandle, so these
-  // effects apply only a later change. Removing either one sets the text back
-  // to the gff prop, which clears the annotations when that is absent too.
-  const appliedGff = useRef(gff)
-  const gffFilehandleKey = JSON.stringify(gffFilehandle ?? null)
-  const appliedGffFilehandle = useRef(gffFilehandleKey)
-  useEffect(() => {
-    if (appliedGffFilehandle.current !== gffFilehandleKey) {
-      appliedGffFilehandle.current = gffFilehandleKey
-      const location = JSON.parse(gffFilehandleKey) as FileLocationType | null
-      if (location) {
-        model.setGFFFilehandle(location)
-      } else {
-        model.setGFF(appliedGff.current)
-      }
-    }
-  }, [model, gffFilehandleKey])
-  useEffect(() => {
-    if (appliedGff.current !== gff) {
-      appliedGff.current = gff
-      model.setGFF(gff)
-    }
-  }, [model, gff])
-
-  // keyed by content, since a host computing a layer inline passes a new array
-  // on every render
-  const colorSchemeKey = JSON.stringify(colorScheme ?? null)
-  useEffect(() => {
-    const scheme = JSON.parse(colorSchemeKey) as ColorScheme | null
-    if (typeof scheme === 'string') {
-      model.setColorSchemeName(scheme)
-    } else if (scheme) {
-      model.setCustomColorScheme(scheme.map)
-    }
-  }, [model, colorSchemeKey])
-  const highlightsKey = JSON.stringify(highlights ?? [])
-  useEffect(() => {
-    model.setHighlights(JSON.parse(highlightsKey))
-  }, [model, highlightsKey])
-  const featuresKey = JSON.stringify(features ?? [])
-  useEffect(() => {
-    model.setFeatures(JSON.parse(featuresKey))
-  }, [model, featuresKey])
-  const selectionKey = JSON.stringify(selection ?? null)
-  useEffect(() => {
-    model.setSelection(JSON.parse(selectionKey) ?? undefined)
-  }, [model, selectionKey])
-  const treeRootKey = JSON.stringify(treeRoot ?? null)
-  useEffect(() => {
-    model.setTreeRoot(JSON.parse(treeRootKey) ?? undefined)
-  }, [model, treeRootKey])
-  const cladesKey = JSON.stringify(clades ?? [])
-  useEffect(() => {
-    model.setClades(JSON.parse(cladesKey))
-  }, [model, cladesKey])
-  const columnTracksKey = JSON.stringify(columnTracks ?? [])
-  useEffect(() => {
-    model.setColumnTracks(JSON.parse(columnTracksKey))
-  }, [model, columnTracksKey])
-  const residueMappingsKey = JSON.stringify(residueMappings ?? [])
-  useEffect(() => {
-    model.setResidueMappings(JSON.parse(residueMappingsKey))
-  }, [model, residueMappingsKey])
-  const rowDataKey = JSON.stringify(rowData ?? {})
-  useEffect(() => {
-    const table = JSON.parse(rowDataKey)
-    // an empty table leaves whatever the snapshot or a filehandle loaded
-    if (Object.keys(table).length) {
-      model.setRowData(table)
-    }
-  }, [model, rowDataKey])
-  const encodingsKey = JSON.stringify(encodings ?? [])
-  useEffect(() => {
-    model.setEncodings(JSON.parse(encodingsKey))
-  }, [model, encodingsKey])
-  const rowPanelsKey = JSON.stringify(rowPanels ?? [])
-  useEffect(() => {
-    model.setRowPanels(JSON.parse(rowPanelsKey))
-  }, [model, rowPanelsKey])
-  const highlightColumnsKey = JSON.stringify(highlightColumns ?? null)
-  useEffect(() => {
-    model.setHighlightedColumns(JSON.parse(highlightColumnsKey) ?? undefined)
-  }, [model, highlightColumnsKey])
+  useSyncedProps(model, props)
 
   const regionKey = JSON.stringify(region ?? null)
   useEffect(() => {
@@ -466,7 +488,7 @@ function Viewer({
       ? when(
           () => model.viewInitialized && model.numColumns > 0,
           () => {
-            model.zoomToRegion(target)
+            model.revealRegion(target)
           },
         )
       : undefined
@@ -477,6 +499,8 @@ function Viewer({
   useModelReaction(model, 'viewport', onViewportChange)
   useModelReaction(model, 'selection', onSelectionChange)
 
+  useImperativeHandle(modelRef, () => model, [model])
+
   const latestOnModel = useRef(onModel)
   useEffect(() => {
     latestOnModel.current = onModel