react-msaview 6.5.0 → 8.0.0

package/src/components/MSAViewer.tsx

@@ -1,18 +1,41 @@
-import React, { useEffect, useState } from 'react'
+import React, { useEffect, 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 Loading from './Loading.tsx'
 
-import type { ColumnTrackSpec, Highlight } from '../types.ts'
+import type { MsaViewModel } from '../model.ts'
+import type {
+  Cell,
+  Clade,
+  ColumnTrackSpec,
+  Encoding,
+  Highlight,
+  Region,
+  ResidueEncoding,
+  ResidueMapping,
+  RowPanelSpec,
+  Viewport,
+} from '../types.ts'
 import type { FileLocation as FileLocationType } from '@jbrowse/core/util/types'
+import type { ThemeOptions } from '@mui/material/styles'
 
-const theme = createJBrowseTheme()
+function resolveTheme(theme: MSAViewerProps['theme']) {
+  return createJBrowseTheme(
+    theme === 'dark'
+      ? { palette: { mode: 'dark' } }
+      : typeof theme === 'object'
+        ? theme
+        : undefined,
+  )
+}
 
-interface MSAViewerProps {
+export interface MSAViewerProps {
   msa?: string
   tree?: string
   gff?: string
@@ -25,6 +48,10 @@ interface MSAViewerProps {
   colWidth?: number
   /** initial per-row pixel height */
   rowHeight?: number
+  /**
+   * 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 */
   highlightColumns?: number[]
   /**
@@ -33,19 +60,136 @@ interface MSAViewerProps {
    * for whole rows, each with an optional `label` and `color`
    */
   highlights?: Highlight[]
+  /**
+   * clades of the tree with a mark drawn over them: `{mrca, tips, mark}` or
+   * `{range, tips, mark}`, where `mark` is `highlight`, `bracket`, `collapse`
+   * or `focus` (see docs/layers.md)
+   */
+  clades?: Clade[]
   /** row name to diff every other row against (matches render as ".") */
   relativeTo?: string
   /** tracks supplied as data: per-column bar values or a text row (see docs/layers.md) */
   columnTracks?: ColumnTrackSpec[]
+  /** which residue of which structure each row's residues are (see docs/layers.md) */
+  residueMappings?: ResidueMapping[]
+  /** extra fields per row name, such as a lineage or a host (see docs/layers.md) */
+  rowData?: Record<string, Record<string, string>>
+  /**
+   * what the viewer's marks read from a table: `{channel, field, scale?}`,
+   * where `channel` is `tipLabel`, `rowTint` or `branch` over `rowData`, or
+   * `featureFill` or `featureLabel` over the annotations (see docs/layers.md)
+   */
+  encodings?: Encoding[]
+  /**
+   * panels between the tree and the alignment, one cell per row:
+   * `{kind: 'strip', field, scale?, width?, header?}` colors each row by a
+   * `rowData` field (see docs/layers.md)
+   */
+  rowPanels?: RowPanelSpec[]
   /** draw the phylogenetic tree (default true); false leaves a labels-only gutter */
   drawTree?: boolean
   /** fixed width (px) of the tree/label area */
   treeAreaWidth?: number
   /** auto-size the tree/label area to the labels (used when drawTree is false) */
   autoTreeAreaWidth?: boolean
+  /** draw branch lengths (default true); false draws a cladogram */
+  showBranchLen?: boolean
+  /**
+   * which channel `colorScheme` paints: `fill` (default) colors the background
+   * of the cell a residue sits in, `color` colors the letter itself and leaves
+   * the background plain, which lets a domain overlay mark each span with a bar
+   * under the row and the residue colors show through
+   */
+  residueEncoding?: ResidueEncoding
+  /**
+   * a span to zoom and scroll to once the alignment loads, and again whenever
+   * it changes: `{row, start, end}` in residues of that row, or `{start, end}`
+   * in columns, 1-based and inclusive
+   */
+  region?: Region
+  /** leave out the toolbar, for a page drawing its own controls */
+  hideHeader?: boolean
+  /**
+   * 'light' (default), 'dark', or MUI theme options (palette, typography)
+   * merged over the JBrowse theme
+   */
+  theme?: 'light' | 'dark' | ThemeOptions
+  /** the cell under the pointer, or undefined when it leaves the alignment */
+  onCellHover?: (cell: Cell | undefined) => void
+  /** the cell a click pinned, or undefined when a click clears it */
+  onCellClick?: (cell: Cell | undefined) => void
+  /** the alignment columns on screen, after every scroll, zoom and resize */
+  onViewportChange?: (viewport: Viewport | undefined) => void
+  /**
+   * the model the viewer built, for the model API; called again with the new
+   * model when msa, tree, gff or a filehandle changes
+   */
+  onModel?: (model: MsaViewModel) => void
 }
 
-export default function MSAViewer({
+type DataSource = Pick<
+  MSAViewerProps,
+  'msa' | 'tree' | 'gff' | 'msaFilehandle' | 'treeFilehandle' | 'gffFilehandle'
+>
+
+function sameSource(a: DataSource, b: DataSource) {
+  return (
+    a.msa === b.msa &&
+    a.tree === b.tree &&
+    a.gff === b.gff &&
+    JSON.stringify([a.msaFilehandle, a.treeFilehandle, a.gffFilehandle]) ===
+      JSON.stringify([b.msaFilehandle, b.treeFilehandle, b.gffFilehandle])
+  )
+}
+
+/**
+ * A new alignment, tree or annotation file needs a new model, so the viewer
+ * remounts when one of those props changes and keeps its model across every
+ * other change.
+ */
+export default function MSAViewer(props: MSAViewerProps) {
+  const { msa, tree, gff, msaFilehandle, treeFilehandle, gffFilehandle } = props
+  const source = {
+    msa,
+    tree,
+    gff,
+    msaFilehandle,
+    treeFilehandle,
+    gffFilehandle,
+  }
+  const [shown, setShown] = useState({ source, generation: 0 })
+  if (!sameSource(shown.source, source)) {
+    setShown({ source, generation: shown.generation + 1 })
+  }
+  return <Viewer key={shown.generation} {...props} />
+}
+
+function useModelReaction<K extends 'hoveredCell' | 'clickedCell' | 'viewport'>(
+  model: MsaViewModel,
+  key: K,
+  handler: ((value: MsaViewModel[K]) => void) | undefined,
+) {
+  const latest = useRef(handler)
+  useEffect(() => {
+    latest.current = handler
+  })
+  const listening = !!handler
+  useEffect(
+    () =>
+      listening
+        ? reaction(
+            () => model[key],
+            value => {
+              latest.current?.(value)
+            },
+            { equals: compareStructural },
+          )
+        : undefined,
+    [model, key, listening],
+  )
+}
+
+function Viewer({
   msa,
   tree,
   gff,
@@ -56,21 +200,43 @@ export default function MSAViewer({
   height,
   colWidth,
   rowHeight,
+  allowedGappyness,
   highlightColumns,
   highlights,
+  clades,
   relativeTo,
   columnTracks,
+  residueMappings,
+  rowData,
+  encodings,
+  rowPanels,
   drawTree,
+  residueEncoding,
   treeAreaWidth,
   autoTreeAreaWidth,
+  showBranchLen,
+  region,
+  hideHeader,
+  theme,
+  onCellHover,
+  onCellClick,
+  onViewportChange,
+  onModel,
 }: MSAViewerProps) {
-  // lazy initializer: the model is created exactly once from the initial props
-  // (a stable MST instance — not a value safe to recompute, so not useMemo)
   const [model] = useState(() =>
     MSAModelF().create({
       type: 'MsaView',
-      ...(msa || tree || gff
-        ? { data: { msa: msa ?? '', tree: tree ?? '', gff } }
+      ...(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 } : {}),
@@ -79,16 +245,29 @@ export default function MSAViewer({
       ...(height ? { height } : {}),
       ...(colWidth ? { colWidth } : {}),
       ...(rowHeight ? { rowHeight } : {}),
+      ...(allowedGappyness !== undefined ? { allowedGappyness } : {}),
       ...(highlightColumns ? { highlightColumns } : {}),
       ...(highlights ? { highlights } : {}),
+      ...(clades ? { clades } : {}),
       ...(relativeTo ? { relativeTo } : {}),
       ...(columnTracks ? { columnTracks } : {}),
+      ...(residueMappings ? { residueMappings } : {}),
+      ...(encodings ? { encodings } : {}),
+      ...(rowPanels ? { rowPanels } : {}),
       ...(drawTree !== undefined ? { drawTree } : {}),
       ...(treeAreaWidth ? { treeAreaWidth } : {}),
       ...(autoTreeAreaWidth ? { autoTreeAreaWidth } : {}),
+      ...(showBranchLen !== undefined ? { showBranchLen } : {}),
+      ...(residueEncoding !== undefined
+        ? { bgColor: residueEncoding === 'fill' }
+        : {}),
     }),
   )
 
+  const destroyTimer = useRef<ReturnType<typeof setTimeout> | undefined>(
+    undefined,
+  )
+
   const [ref, { width }] = useMeasure()
   useEffect(() => {
     if (width) {
@@ -96,8 +275,145 @@ export default function MSAViewer({
     }
   }, [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 (colorScheme !== undefined) {
+      model.setColorSchemeName(colorScheme)
+    }
+  }, [model, colorScheme])
+  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 (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])
+
+  // keyed by content, since a host computing a layer inline passes a new array
+  // on every render
+  const highlightsKey = JSON.stringify(highlights ?? [])
+  useEffect(() => {
+    model.setHighlights(JSON.parse(highlightsKey))
+  }, [model, highlightsKey])
+  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])
+
+  const regionKey = JSON.stringify(region ?? null)
+  useEffect(() => {
+    const target = JSON.parse(regionKey) as Region | null
+    return target
+      ? when(
+          () => model.viewInitialized && model.numColumns > 0,
+          () => {
+            model.zoomToRegion(target)
+          },
+        )
+      : undefined
+  }, [model, regionKey])
+
+  useModelReaction(model, 'hoveredCell', onCellHover)
+  useModelReaction(model, 'clickedCell', onCellClick)
+  useModelReaction(model, 'viewport', onViewportChange)
+
+  const latestOnModel = useRef(onModel)
+  useEffect(() => {
+    latestOnModel.current = onModel
+  })
+  useEffect(() => {
+    latestOnModel.current?.(model)
+  }, [model])
+
+  // destroy releases the model's matchMedia listener and fetches. It waits a
+  // tick because StrictMode remounts with the same state, and the remount's
+  // effect cancels it.
+  useEffect(() => {
+    if (destroyTimer.current !== undefined) {
+      clearTimeout(destroyTimer.current)
+      destroyTimer.current = undefined
+    }
+    return () => {
+      destroyTimer.current = setTimeout(() => {
+        destroyTimer.current = undefined
+        if (isAlive(model)) {
+          destroy(model)
+        }
+      })
+    }
+  }, [model])
+
   return (
-    <ThemeProvider theme={theme}>
+    <ThemeProvider theme={resolveTheme(theme)}>
       <div ref={ref}>
         <Loading model={model} />
       </div>

package/src/components/PortalTooltip.tsx

@@ -0,0 +1,47 @@
+import React from 'react'
+
+import { makeStyles } from '@jbrowse/core/util/tss-react'
+import { createPortal } from 'react-dom'
+
+const useStyles = makeStyles()(theme => ({
+  tooltip: {
+    position: 'fixed',
+    pointerEvents: 'none',
+    zIndex: 10000,
+    backgroundColor: theme.palette.grey[700],
+    color: theme.palette.common.white,
+    padding: '4px 8px',
+    borderRadius: 4,
+    fontSize: 12,
+    whiteSpace: 'nowrap',
+    maxWidth: 300,
+    overflow: 'hidden',
+    textOverflow: 'ellipsis',
+  },
+}))
+
+/**
+ * A tooltip beside the pointer, portaled to the body. A panel's scroll
+ * transform is a containing block, so a fixed tooltip left inside it would
+ * position against the scrolled content instead of the window.
+ */
+export default function PortalTooltip({
+  clientX,
+  clientY,
+  children,
+}: {
+  clientX: number
+  clientY: number
+  children: React.ReactNode
+}) {
+  const { classes } = useStyles()
+  return createPortal(
+    <div
+      className={classes.tooltip}
+      style={{ left: clientX + 12, top: clientY + 12 }}
+    >
+      {children}
+    </div>,
+    document.body,
+  )
+}

package/src/components/ResizeHandles.tsx

@@ -5,7 +5,7 @@ import { observer } from 'mobx-react'
 import DragHandle from './DragHandle.tsx'
 
 import type { MsaViewModel } from '../model.ts'
-import type { TrackKind } from '../types.ts'
+import type { BasicTrack } from '../types.ts'
 
 export const VerticalResizeHandle = observer(function ({
   model,
@@ -51,53 +51,38 @@ export const HorizontalResizeHandle = observer(function ({
   )
 })
 
-// The height behind each resizable track kind. Both bar tracks read one height
-// so conservation and property conservation stay directly comparable; the logo
-// keeps its own, being taller by default. Text tracks are absent: they are one
-// alignment row tall and follow rowHeight, so the zoom controls already size
-// them.
-const trackHeights: Partial<
-  Record<
-    TrackKind,
-    {
-      get: (model: MsaViewModel) => number
-      set: (model: MsaViewModel, height: number) => void
-    }
-  >
-> = {
-  bar: {
-    get: model => model.conservationTrackHeight,
-    set: (model, height) => {
-      model.setConservationTrackHeight(height)
-    },
-  },
-  logo: {
-    get: model => model.sequenceLogoTrackHeight,
-    set: (model, height) => {
-      model.setSequenceLogoTrackHeight(height)
-    },
-  },
-}
-
 export const TrackResizeHandle = observer(function ({
   model,
-  kind,
+  track,
 }: {
   model: MsaViewModel
-  kind: TrackKind
+  track: BasicTrack
 }) {
-  const height = trackHeights[kind]
+  const { id, heightKey, height } = track.model
+  // tracks sharing a key resize together, so only the last turned-on one of
+  // them carries the divider: a second between conservation and property
+  // conservation would move the pair this one already moves. The drag divides
+  // across the group, so its bottom edge follows the cursor rather than half
+  const siblings = model.turnedOnTracks.filter(
+    t => t.model.heightKey === heightKey,
+  )
+  const count = siblings.length
   const onDrag = useCallback(
     (delta: number, startHeight: number) => {
-      height?.set(model, Math.max(10, startHeight + delta))
+      if (heightKey) {
+        model.setTrackHeight(
+          heightKey,
+          Math.max(10, startHeight + delta / count),
+        )
+      }
     },
-    [model, height],
+    [model, heightKey, count],
   )
-  return height ? (
+  return heightKey && siblings.at(-1)?.model.id === id ? (
     <DragHandle
       axis="y"
       variant="resizer"
-      getStart={() => height.get(model)}
+      getStart={() => height}
       onDrag={onDrag}
       style={{
         position: 'absolute',

package/src/components/SequenceTextArea.tsx

@@ -7,17 +7,17 @@ import { getUngappedSequence } from 'msa-parsers'
 import Checkbox2 from './Checkbox2.tsx'
 import CopyButton from './CopyButton.tsx'
 
-const useStyles = makeStyles()({
+const useStyles = makeStyles()(theme => ({
   textAreaFont: {
     fontFamily: 'Courier New',
     wordWrap: 'break-word',
   },
   dialogContent: {
-    background: 'lightgrey',
+    background: theme.palette.action.selected,
     margin: 4,
     minWidth: '80em',
   },
-})
+}))
 
 export default function SequenceTextArea({ str }: { str: [string, string][] }) {
   const { classes } = useStyles()