react-msaview 7.0.0 → 8.0.0

package/src/columnStats.ts

@@ -0,0 +1,58 @@
+import type { ColumnCounts } from './columnCounts.ts'
+
+export interface ColumnStats {
+  col: number
+  total: number
+  gaps: number
+  gapFraction: number
+  conservation: number
+  propertyConservation: number | undefined
+  consensusLetter: string
+  consensusCount: number
+  consensusFraction: number
+  distribution: [string, number][]
+}
+
+/**
+ * Summarize one column: consensus residue and its identity fraction, the two
+ * conservation scores, gap fraction, and the non-gap residue distribution
+ * sorted by count. undefined past the end of the alignment or for a column with
+ * no sequences.
+ *
+ * A module-level function: a getter that reached the method through `this` made
+ * TypeScript infer the whole views object to type it, and fell back to `any`.
+ */
+export function columnStats({
+  col,
+  colStats,
+  conservation,
+  propertyConservation,
+}: {
+  col: number
+  colStats: ColumnCounts
+  conservation: number[]
+  propertyConservation: number[]
+}): ColumnStats | undefined {
+  if (col >= colStats.numColumns) {
+    return undefined
+  }
+  const total = colStats.total(col)
+  if (!total) {
+    return undefined
+  }
+  const gaps = colStats.gapCount(col)
+  const distribution = colStats.residueEntries(col).sort((a, b) => b[1] - a[1])
+  const consensus = distribution[0]
+  return {
+    col,
+    total,
+    gaps,
+    gapFraction: gaps / total,
+    conservation: conservation[col] ?? 0,
+    propertyConservation: propertyConservation[col],
+    consensusLetter: consensus?.[0] ?? '',
+    consensusCount: consensus?.[1] ?? 0,
+    consensusFraction: consensus ? consensus[1] / total : 0,
+    distribution,
+  }
+}

package/src/components/DragHandle.tsx

@@ -1,7 +1,11 @@
 import React, { useState } from 'react'
 
+import { useTheme } from '@mui/material'
+
 import { useDragScroll } from '../useDragScroll.ts'
 
+import type { Theme } from '@mui/material'
+
 export const scrollbarThumbFill = 'rgba(66,119,127,0.3)'
 
 // The scroll thumbs (minimap, vertical scrollbar) and the resize dividers are
@@ -11,23 +15,29 @@ export const scrollbarThumbFill = 'rgba(66,119,127,0.3)'
 const variants: Record<
   'thumb' | 'resizer',
   {
-    fill: string
-    fillHovered: string
+    fill: (theme: Theme) => string
+    fillHovered: (theme: Theme) => string
     cursor: (axis: 'x' | 'y') => string
     position: React.CSSProperties['position']
     zIndex?: number
   }
 > = {
   thumb: {
-    fill: scrollbarThumbFill,
-    fillHovered: 'rgba(66,119,127,0.6)',
+    fill: () => scrollbarThumbFill,
+    fillHovered: () => 'rgba(66,119,127,0.6)',
     cursor: () => 'pointer',
     position: 'absolute',
     zIndex: 100,
   },
   resizer: {
-    fill: 'rgba(200,200,200)',
-    fillHovered: 'rgba(150,150,150)',
+    fill: theme =>
+      theme.palette.mode === 'dark'
+        ? theme.palette.grey[800]
+        : 'rgba(200,200,200)',
+    fillHovered: theme =>
+      theme.palette.mode === 'dark'
+        ? theme.palette.grey[600]
+        : 'rgba(150,150,150)',
     cursor: axis => (axis === 'x' ? 'ew-resize' : 'ns-resize'),
     position: 'relative',
   },
@@ -54,6 +64,7 @@ export default function DragHandle({
   onDrag: (delta: number, startValue: number) => void
   style: React.CSSProperties
 }) {
+  const theme = useTheme()
   const [hovered, setHovered] = useState(false)
   const { startDrag } = useDragScroll(axis, onDrag)
   const { fill, fillHovered, cursor, position, zIndex } = variants[variant]
@@ -73,7 +84,7 @@ export default function DragHandle({
         position,
         zIndex,
         cursor: cursor(axis),
-        background: hovered ? fillHovered : fill,
+        background: hovered ? fillHovered(theme) : fill(theme),
         ...style,
       }}
     />

package/src/components/Loading.tsx

@@ -109,12 +109,8 @@ const Loading = observer(function ({ model }: { model: MsaViewModel }) {
             <MSAView model={model} />
           )
         ) : error ? (
-          // Ahead of the spinner, because a failed load KEEPS its filehandle --
-          // only an abort clears it. So hasPendingFilehandle stays true, this
-          // fell to the spinner below, and the ImportForm that renders
-          // `model.error` was never reached: the reader got "Downloading file"
-          // and a Cancel button for as long as they were willing to watch it.
-          // Found on AlphaFold's files/msa/ prefix answering 403 to every key.
+          // checked before the spinner: a failed load keeps its filehandle
+          // (only an abort clears it), so hasPendingFilehandle stays true
           <Reset model={model} error={error} />
         ) : hasPendingFilehandle || isLoading ? (
           <LoadingSpinner model={model} />

package/src/components/MSAView.tsx

@@ -12,16 +12,27 @@ import Header from './header/Header.tsx'
 import Minimap from './minimap/Minimap.tsx'
 import MSAPanel from './msa/MSAPanel.tsx'
 import { clickColor, hoverColor } from './overlayColors.ts'
+import RowPanelHeaders from './rowpanels/RowPanelHeaders.tsx'
+import RowPanels from './rowpanels/RowPanels.tsx'
+import TreeOverview from './tree/TreeOverview.tsx'
 import TreePanel from './tree/TreePanel.tsx'
 import TreeRuler from './tree/TreeRuler.tsx'
 
 import type { MsaViewModel } from '../model.ts'
 
+// The band above the panels: the tree overview and scale bar, the strip
+// headers, and the minimap over the alignment. The spacer stands in for the
+// resize handle, so the minimap starts exactly where the alignment canvas does.
 const TopArea = observer(function ({ model }: { model: MsaViewModel }) {
-  const { showHorizontalScrollbar } = model
+  const { showHorizontalScrollbar, showTreeOverview, resizeHandleWidth } = model
   return (
     <div style={{ display: 'flex' }}>
-      <TreeRuler model={model} />
+      <div style={{ flexShrink: 0 }}>
+        {showTreeOverview ? <TreeOverview model={model} /> : null}
+        <TreeRuler model={model} />
+      </div>
+      <RowPanelHeaders model={model} />
+      <div style={{ width: resizeHandleWidth, flexShrink: 0 }} />
       {showHorizontalScrollbar ? <Minimap model={model} /> : null}
     </div>
   )
@@ -38,6 +49,7 @@ const TrackColumnIndicator = observer(function ({
     colWidth,
     scrollX,
     treeAreaWidth,
+    rowPanelsWidth,
     resizeHandleWidth,
     totalTrackAreaHeight,
     msaCanvasWidth,
@@ -53,7 +65,7 @@ const TrackColumnIndicator = observer(function ({
     <div
       style={{
         position: 'absolute',
-        left: treeAreaWidth + resizeHandleWidth,
+        left: treeAreaWidth + rowPanelsWidth + resizeHandleWidth,
         top: 0,
         width: msaCanvasWidth,
         height: totalTrackAreaHeight,
@@ -102,6 +114,7 @@ const MainArea = observer(function ({ model }: { model: MsaViewModel }) {
   return (
     <div style={{ display: 'flex' }}>
       <TreePanel model={model} />
+      <RowPanels model={model} />
       <VerticalResizeHandle model={model} />
       <MSAPanel model={model} />
       {showVerticalScrollbar ? <VerticalScrollbar model={model} /> : null}
@@ -120,14 +133,15 @@ const View = observer(function ({ model }: { model: MsaViewModel }) {
 })
 
 const MSAView = observer(function ({ model }: { model: MsaViewModel }) {
-  const { height, viewInitialized, DialogComponent, DialogProps } = model
+  const { height, hideHeader, viewInitialized, DialogComponent, DialogProps } =
+    model
 
   return (
     <div>
       {viewInitialized ? (
         <>
           <div style={{ height, overflow: 'hidden' }}>
-            <Header model={model} />
+            {hideHeader ? null : <Header model={model} />}
             <View model={model} />
           </div>
           <HorizontalResizeHandle model={model} />

package/src/components/MSAViewer.tsx

@@ -4,16 +4,38 @@ 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, ResidueMapping } 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
@@ -27,9 +49,7 @@ interface MSAViewerProps {
   /** initial per-row pixel height */
   rowHeight?: number
   /**
-   * hide columns at least this percent gaps (default 100, i.e. hide nothing).
-   * A deep family's alignment is mostly insertions carried by a few members;
-   * dropping those columns is what makes the rest readable
+   * 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 */
@@ -40,21 +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
+}
+
+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} />
 }
 
-export default function MSAViewer({
+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,
@@ -68,20 +203,40 @@ export default function MSAViewer({
   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 } : {}),
@@ -93,12 +248,19 @@ export default function MSAViewer({
       ...(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' }
+        : {}),
     }),
   )
 
@@ -113,14 +275,8 @@ export default function MSAViewer({
     }
   }, [model, width])
 
-  // The props below stay live after mount: change one and it drives the model,
-  // so a host can put a control on the viewer -- an expand button, a diff
-  // toggle, a color-scheme picker -- without remounting it and re-fetching its
-  // alignment. Each effect depends only on its own prop, so a change the user
-  // makes inside the viewer (picking a scheme from the menu, dragging a row
-  // taller) survives the host's next render rather than being snapped back.
-  // Data props are not among them: new msa/tree/gff is a different alignment,
-  // which is a new model, which React spells `key`.
+  // 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)
@@ -156,18 +312,34 @@ export default function MSAViewer({
       model.setTreeAreaWidth(treeAreaWidth)
     }
   }, [model, treeAreaWidth])
-  // unguarded: dropping the prop is how a host turns the reference diff back off
+  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])
 
-  // the data layers, keyed by content: a host that computes one inline hands a
-  // new array on every render, and replacing the model's copy each time would
-  // redraw the overlay for nothing
+  // 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))
@@ -176,15 +348,55 @@ export default function MSAViewer({
   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])
 
-  // the model owns a matchMedia listener and whatever fetches its filehandles
-  // started, so an unmounted viewer that keeps its model keeps those too. The
-  // destroy is deferred by a tick because React's StrictMode mounts, unmounts
-  // and remounts with the same state: the remount's effect cancels it
+  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)
@@ -201,7 +413,7 @@ export default function MSAViewer({
   }, [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,
+  )
+}