react-msaview 8.2.0 → 8.4.0

package/src/components/MSAViewer.tsx

@@ -13,13 +13,19 @@ import type { MsaViewModel } from '../model.ts'
 import type {
   Cell,
   Clade,
+  ColorScheme,
   ColumnTrackSpec,
   Encoding,
+  Feature,
   Highlight,
+  MsaSelection,
   Region,
   ResidueEncoding,
   ResidueMapping,
+  RowDataInput,
   RowPanelSpec,
+  TreeOrder,
+  TreeRoot,
   Viewport,
 } from '../types.ts'
 import type { FileLocation as FileLocationType } from '@jbrowse/core/util/types'
@@ -42,7 +48,11 @@ export interface MSAViewerProps {
   msaFilehandle?: FileLocationType
   treeFilehandle?: FileLocationType
   gffFilehandle?: FileLocationType
-  colorScheme?: string
+  /**
+   * a scheme name from the built-in table, or `{map}`, a color per residue
+   * letter that leaves every other letter uncolored
+   */
+  colorScheme?: ColorScheme
   height?: number
   /** initial per-column pixel width (zoom level) */
   colWidth?: number
@@ -60,6 +70,13 @@ export interface MSAViewerProps {
    * for whole rows, each with an optional `label` and `color`
    */
   highlights?: Highlight[]
+  /**
+   * features on the rows as data, drawn with the GFF's: `{row, start, end}` in
+   * residues of that row, 1-based and inclusive, with an optional `name`,
+   * `description`, `type`, `strand` and `color`, and any other field an
+   * encoding reads (see docs/layers.md)
+   */
+  features?: Feature[]
   /**
    * clades of the tree with a mark drawn over them: `{mrca, tips, mark}` or
    * `{range, tips, mark}`, where `mark` is `highlight`, `bracket`, `collapse`
@@ -73,7 +90,7 @@ export interface MSAViewerProps {
   /** 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>>
+  rowData?: RowDataInput
   /**
    * what the viewer's marks read from a table: `{channel, field, scale?}`,
    * where `channel` is `tipLabel`, `rowTint` or `branch` over `rowData`, or
@@ -94,6 +111,17 @@ export interface MSAViewerProps {
   autoTreeAreaWidth?: boolean
   /** draw branch lengths (default true); false draws a cladogram */
   showBranchLen?: boolean
+  /**
+   * the order each node's children draw in: `branchLength` (default,
+   * shortest first), `input` (as the file gives them), `ladderize` (fewest
+   * tips first) or `ladderizeReverse` (most tips first)
+   */
+  treeOrder?: TreeOrder
+  /**
+   * reroot the tree: `midpoint`, or `{outgroup: [tip names]}` on the branch
+   * above those tips' common ancestor
+   */
+  treeRoot?: TreeRoot
   /**
    * which channel `colorScheme` paints: `fill` (default) colors the background
    * of the cell a residue sits in, `color` colors the letter itself and leaves
@@ -107,6 +135,11 @@ export interface MSAViewerProps {
    * in columns, 1-based and inclusive
    */
   region?: Region
+  /**
+   * the selected block: `{start, end}` columns of the file, 1-based and
+   * inclusive, and `rows` by name, every row where absent
+   */
+  selection?: MsaSelection
   /** leave out the toolbar, for a page drawing its own controls */
   hideHeader?: boolean
   /**
@@ -120,43 +153,48 @@ export interface MSAViewerProps {
   onCellClick?: (cell: Cell | undefined) => void
   /** the alignment columns on screen, after every scroll, zoom and resize */
   onViewportChange?: (viewport: Viewport | undefined) => void
+  /**
+   * the selected block, after each change a drag, the header menu, Escape or
+   * the `selection` prop makes, or undefined when it clears
+   */
+  onSelectionChange?: (selection: MsaSelection | 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
+   * model when msa, tree, 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' | 'gff' | 'msaFilehandle' | 'treeFilehandle' | 'gffFilehandle'
+  'msa' | 'tree' | 'msaFilehandle' | 'treeFilehandle'
 >
 
 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])
+    JSON.stringify([a.msaFilehandle, a.treeFilehandle]) ===
+      JSON.stringify([b.msaFilehandle, b.treeFilehandle])
   )
 }
 
 /**
- * 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.
+ * 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.
  */
 export default function MSAViewer(props: MSAViewerProps) {
-  const { msa, tree, gff, msaFilehandle, treeFilehandle, gffFilehandle } = props
-  const source = {
-    msa,
-    tree,
-    gff,
-    msaFilehandle,
-    treeFilehandle,
-    gffFilehandle,
-  }
+  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 })
@@ -164,7 +202,9 @@ export default function MSAViewer(props: MSAViewerProps) {
   return <Viewer key={shown.generation} {...props} />
 }
 
-function useModelReaction<K extends 'hoveredCell' | 'clickedCell' | 'viewport'>(
+function useModelReaction<
+  K extends 'hoveredCell' | 'clickedCell' | 'viewport' | 'selection',
+>(
   model: MsaViewModel,
   key: K,
   handler: ((value: MsaViewModel[K]) => void) | undefined,
@@ -203,6 +243,7 @@ function Viewer({
   allowedGappyness,
   highlightColumns,
   highlights,
+  features,
   clades,
   relativeTo,
   columnTracks,
@@ -215,12 +256,16 @@ function Viewer({
   treeAreaWidth,
   autoTreeAreaWidth,
   showBranchLen,
+  treeOrder,
+  treeRoot,
   region,
+  selection,
   hideHeader,
   theme,
   onCellHover,
   onCellClick,
   onViewportChange,
+  onSelectionChange,
   onModel,
 }: MSAViewerProps) {
   const [model] = useState(() =>
@@ -241,13 +286,15 @@ function Viewer({
       ...(msaFilehandle ? { msaFilehandle } : {}),
       ...(treeFilehandle ? { treeFilehandle } : {}),
       ...(gffFilehandle ? { gffFilehandle } : {}),
-      ...(colorScheme ? { colorSchemeName: colorScheme } : {}),
+      ...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 } : {}),
@@ -258,6 +305,8 @@ function Viewer({
       ...(treeAreaWidth ? { treeAreaWidth } : {}),
       ...(autoTreeAreaWidth ? { autoTreeAreaWidth } : {}),
       ...(showBranchLen !== undefined ? { showBranchLen } : {}),
+      ...(treeOrder ? { treeOrder } : {}),
+      ...(treeRoot ? { treeRoot } : {}),
       ...(residueEncoding !== undefined
         ? { bgColor: residueEncoding === 'fill' }
         : {}),
@@ -282,11 +331,6 @@ function Viewer({
       model.setHeight(height)
     }
   }, [model, height])
-  useEffect(() => {
-    if (colorScheme !== undefined) {
-      model.setColorSchemeName(colorScheme)
-    }
-  }, [model, colorScheme])
   useEffect(() => {
     if (colWidth !== undefined) {
       model.setColWidth(colWidth)
@@ -317,6 +361,11 @@ function Viewer({
       model.setShowBranchLen(showBranchLen)
     }
   }, [model, showBranchLen])
+  useEffect(() => {
+    if (treeOrder !== undefined) {
+      model.setTreeOrder(treeOrder)
+    }
+  }, [model, treeOrder])
   useEffect(() => {
     if (residueEncoding !== undefined) {
       model.setBgColor(residueEncoding === 'fill')
@@ -330,12 +379,57 @@ function Viewer({
     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))
@@ -385,6 +479,7 @@ function Viewer({
   useModelReaction(model, 'hoveredCell', onCellHover)
   useModelReaction(model, 'clickedCell', onCellClick)
   useModelReaction(model, 'viewport', onViewportChange)
+  useModelReaction(model, 'selection', onSelectionChange)
 
   const latestOnModel = useRef(onModel)
   useEffect(() => {

package/src/components/MetadataTable.tsx

@@ -0,0 +1,55 @@
+import React from 'react'
+
+import { makeStyles } from '@jbrowse/core/util/tss-react'
+import { Table, TableBody, TableCell, TableRow } from '@mui/material'
+
+const useStyles = makeStyles()({
+  key: {
+    fontWeight: 'bold',
+    verticalAlign: 'top',
+  },
+  value: {
+    whiteSpace: 'pre-wrap',
+    wordBreak: 'break-word',
+  },
+})
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null && !Array.isArray(value)
+}
+
+export function isEmpty(value: unknown) {
+  return isRecord(value) && Object.keys(value).length === 0
+}
+
+export default function MetadataTable({
+  record,
+}: {
+  record: Record<string, unknown>
+}) {
+  const { classes } = useStyles()
+  return (
+    <Table size="small">
+      <TableBody>
+        {Object.entries(record)
+          .filter(([, value]) => value != null && !isEmpty(value))
+          .map(([key, value]) => (
+            <TableRow key={key}>
+              <TableCell component="th" className={classes.key}>
+                {key}
+              </TableCell>
+              <TableCell className={classes.value}>
+                {isRecord(value) ? (
+                  <MetadataTable record={value} />
+                ) : Array.isArray(value) ? (
+                  value.join('\n')
+                ) : (
+                  String(value)
+                )}
+              </TableCell>
+            </TableRow>
+          ))}
+      </TableBody>
+    </Table>
+  )
+}

package/src/components/SequenceTextArea.tsx

@@ -1,9 +1,10 @@
 import React, { useState } from 'react'
 
 import { makeStyles } from '@jbrowse/core/util/tss-react'
-import { TextField } from '@mui/material'
+import { Button, TextField } from '@mui/material'
 import { getUngappedSequence } from 'msa-parsers'
 
+import { saveAs } from '../vendor/fileSaver.ts'
 import Checkbox2 from './Checkbox2.tsx'
 import CopyButton from './CopyButton.tsx'
 
@@ -18,19 +19,59 @@ const useStyles = makeStyles()(theme => ({
   },
 }))
 
+export const maxShownRecords = 100
+export const maxShownChars = 200_000
+
+function fastaRecord([name, seq]: [string, string], showGaps: boolean) {
+  return `>${name}\n${showGaps ? seq : getUngappedSequence(seq)}`
+}
+
+function isAllGaps(seq: string) {
+  return !/[^.-]/.test(seq)
+}
+
+/**
+ * The first records of `rows` as FASTA, up to `maxShownRecords` records or
+ * `maxShownChars` characters, whichever comes first. A textarea holding every
+ * row of a large alignment freezes the page.
+ */
+export function fastaPreview(rows: [string, string][], showGaps: boolean) {
+  const shown: string[] = []
+  let chars = 0
+  for (const row of rows) {
+    if (shown.length >= maxShownRecords || chars >= maxShownChars) {
+      break
+    }
+    const record = fastaRecord(row, showGaps)
+    shown.push(record)
+    chars += record.length + 1
+  }
+  return { text: shown.join('\n'), hidden: rows.length - shown.length }
+}
+
 export default function SequenceTextArea({ str }: { str: [string, string][] }) {
   const { classes } = useStyles()
   const [showGaps, setShowGaps] = useState(false)
   const [showEmpty, setShowEmpty] = useState(false)
 
-  const disp = str
-    .map(([s1, s2]) => [s1, showGaps ? s2 : getUngappedSequence(s2)] as const)
-    .filter(([, s2]) => showEmpty || !!s2)
-    .map(([s1, s2]) => `>${s1}\n${s2}`)
-    .join('\n')
+  const rows = showEmpty
+    ? str
+    : str.filter(([, seq]) => (showGaps ? !!seq : !isAllGaps(seq)))
+  const { text, hidden } = fastaPreview(rows, showGaps)
+  const fullText = () => rows.map(row => fastaRecord(row, showGaps)).join('\n')
   return (
     <>
-      <CopyButton text={disp} />
+      <CopyButton text={fullText} />
+      <Button
+        onClick={() => {
+          saveAs(
+            new Blob([fullText()], { type: 'text/plain' }),
+            'sequences.fasta',
+          )
+        }}
+      >
+        Download
+      </Button>
       <Checkbox2
         label="Show gaps"
         checked={showGaps}
@@ -52,7 +93,12 @@ export default function SequenceTextArea({ str }: { str: [string, string][] }) {
         minRows={5}
         maxRows={10}
         fullWidth
-        value={disp}
+        value={text}
+        helperText={
+          hidden > 0
+            ? `Showing ${rows.length - hidden} of ${rows.length.toLocaleString()} sequences. ${hidden.toLocaleString()} more are in the copy and the download.`
+            : undefined
+        }
         slotProps={{
           input: {
             readOnly: true,

package/src/components/StatusMessage.tsx

@@ -0,0 +1,70 @@
+import React from 'react'
+
+import { LoadingEllipses } from '@jbrowse/core/ui'
+import { makeStyles } from '@jbrowse/core/util/tss-react'
+import { Button, CircularProgress, Typography } from '@mui/material'
+import { observer } from 'mobx-react'
+
+import type { MsaViewModel } from '../model.ts'
+
+const useStyles = makeStyles()({
+  page: {
+    display: 'flex',
+    alignItems: 'center',
+    gap: 12,
+    padding: 20,
+  },
+  header: {
+    display: 'flex',
+    alignItems: 'center',
+    gap: 4,
+    margin: 'auto',
+    marginLeft: 10,
+  },
+})
+
+/**
+ * The model's status line with its Cancel button: a spinner and a heading in
+ * place of the view while it loads, or a line in the header afterwards, which
+ * disappears when there is no status.
+ */
+const StatusMessage = observer(function ({
+  model,
+  variant,
+}: {
+  model: MsaViewModel
+  variant: 'page' | 'header'
+}) {
+  const { status } = model
+  const { classes } = useStyles()
+  if (variant === 'header' && !status) {
+    return null
+  }
+  const message = status?.msg ?? 'Loading...'
+  const onCancel = status?.onCancel
+  return (
+    <div className={classes[variant]}>
+      {variant === 'page' ? (
+        <>
+          <CircularProgress size={24} />
+          <Typography variant="h6">{message}</Typography>
+        </>
+      ) : (
+        <LoadingEllipses message={message} component="span" />
+      )}
+      {onCancel ? (
+        <Button
+          variant={variant === 'page' ? 'outlined' : 'text'}
+          size="small"
+          onClick={() => {
+            onCancel()
+          }}
+        >
+          Cancel
+        </Button>
+      ) : null}
+    </div>
+  )
+})
+
+export default StatusMessage

package/src/components/Track.tsx

@@ -7,6 +7,7 @@ import { IconButton, Menu, MenuItem } from '@mui/material'
 import { observer } from 'mobx-react'
 
 import { useWheelScroll } from '../useWheelScroll.ts'
+import { onMsaKey } from './msa/msaKeys.ts'
 import TrackTooltipContent from './tracks/TrackTooltipContent.tsx'
 import { useTrackHover } from './tracks/useTrackHover.ts'
 
@@ -146,7 +147,7 @@ const Track = observer(function ({
   )
   useWheelScroll({ ref, onScrollX })
   const { classes } = useStyles()
-  const { hover, onMouseMove, onMouseLeave } = useTrackHover({
+  const { anchor, onMouseMove, onMouseDown, onMouseLeave } = useTrackHover({
     model,
     tooltip: showColumnStats,
   })
@@ -162,19 +163,35 @@ const Track = observer(function ({
       <div
         ref={ref}
         data-testid={`track_${track.model.id}`}
+        tabIndex={-1}
+        style={{ outline: 'none' }}
+        onKeyDown={event => {
+          if (onMsaKey(model, event)) {
+            event.preventDefault()
+          }
+        }}
         onMouseMove={event => {
           if (ref.current) {
             onMouseMove(event, ref.current)
           }
         }}
+        onMouseDown={event => {
+          if (ref.current) {
+            onMouseDown(event, ref.current)
+          }
+        }}
         onMouseLeave={() => {
           onMouseLeave()
         }}
       >
         <track.ReactComponent model={model} track={track} />
-        {hover ? (
-          <BaseTooltip clientPoint={{ x: hover.x, y: hover.y + 15 }}>
-            <TrackTooltipContent model={model} track={track} col={hover.col} />
+        {anchor ? (
+          <BaseTooltip clientPoint={anchor.clientPoint}>
+            <TrackTooltipContent
+              model={model}
+              track={track}
+              col={anchor.value}
+            />
           </BaseTooltip>
         ) : null}
       </div>

package/src/components/VerticalScrollbar.tsx

@@ -23,6 +23,13 @@ const VerticalScrollbar = observer(({ model }: { model: MsaViewModel }) => {
 
   return (
     <div
+      onMouseDown={event => {
+        if (event.button === 0 && event.target === event.currentTarget) {
+          const y =
+            event.clientY - event.currentTarget.getBoundingClientRect().top
+          model.setScrollY(-y / unit + msaAreaHeight / 2)
+        }
+      }}
       style={{
         position: 'relative',
         width,

package/src/components/dialogs/ExportSVGDialog.tsx

@@ -15,6 +15,7 @@ import {
   Typography,
   useTheme,
 } from '@mui/material'
+import { observer } from 'mobx-react'
 
 import Checkbox2 from '../Checkbox2.tsx'
 
@@ -30,7 +31,7 @@ function afterPaint(fn: () => void) {
   })
 }
 
-export default function ExportSVGDialog({
+const ExportSVGDialog = observer(function ({
   model,
   onClose,
 }: {
@@ -181,4 +182,6 @@ export default function ExportSVGDialog({
       </DialogActions>
     </Dialog>
   )
-}
+})
+
+export default ExportSVGDialog