react-msaview 7.0.0 → 8.1.0

package/src/scales.ts

@@ -0,0 +1,47 @@
+import { createPaletteMap } from './createPaletteMap.ts'
+import { paletteNamed } from './ggplotPalettes.ts'
+
+import type { LegendEntry } from './types.ts'
+
+/** how a channel reads a field: a palette by name, or a color per value */
+export interface ScaleSpec {
+  palette?: string
+  map?: Record<string, string>
+}
+
+export interface ResolvedScale {
+  kind: 'categorical'
+  colorOf: (value: string) => string | undefined
+  legend: LegendEntry[]
+}
+
+/**
+ * The scale a channel reads its field through. `values` are the field's values,
+ * in any order and with repeats; the domain is their distinct values sorted, so
+ * a value keeps its color when rows are re-ordered, collapsed or filtered.
+ *
+ * `{map}` colors the values the producer named and leaves the rest uncolored.
+ * `{palette}` takes the colors of a named palette, and a spec with neither
+ * takes the ggplot palette of the domain's size. Every scale is categorical
+ * today; a continuous one waits for a caller.
+ */
+export function resolveScale(
+  spec: ScaleSpec | undefined,
+  values: Iterable<string>,
+): ResolvedScale {
+  const domain = [...new Set(values)].sort((a, b) => a.localeCompare(b))
+  const { map, palette } = spec ?? {}
+  const colors = map ?? createPaletteMap(domain, paletteNamed(palette))
+  const present = new Set(domain)
+  const labels = map ? Object.keys(map).filter(v => present.has(v)) : domain
+  return {
+    kind: 'categorical',
+    colorOf: (value: string) => colors[value],
+    // a categorical value is its own label, and the id a legend keys on
+    legend: labels.map(value => ({
+      id: value,
+      label: value,
+      color: colors[value]!,
+    })),
+  }
+}

package/src/seqPosToGlobalCol.ts

@@ -2,9 +2,8 @@
  * The global column of every ungapped sequence position in a row, i.e.
  * index[seqPos] is the column holding the seqPos-th non-gap character.
  *
- * A row is indexed once and then answers seqPos -> column by lookup, which is
- * what makes the domain overlay affordable: it resolves one position per feature
- * per row on every redraw, and scanning the row for each would be quadratic.
+ * The domain overlay resolves one position per feature per row on every redraw,
+ * and scanning the row for each would be quadratic.
  *
  * @example
  * // Row: "A-TG-C" (A at 0, T at 2, G at 3, C at 5)

package/src/sequenceLogo.ts

@@ -19,18 +19,13 @@ export function maxBitsFor(sequenceType: 'dna' | 'rna' | 'amino') {
  * stack bottom-up in array order.
  *
  * Heights follow Schneider & Stephens: the column's information content is
- * `log2(alphabet) - H` bits, and each residue takes the share of that its own
- * frequency earns. Frequencies come from the non-gap residues only, so a column
- * of two residues and eight gaps is read as a two-way choice rather than a
- * ten-way one -- otherwise every gappy column would look uninformative for the
- * wrong reason.
+ * `log2(alphabet) - H` bits, split among residues by frequency. Frequencies
+ * count non-gap residues only, so two residues and eight gaps form a two-way
+ * choice.
  *
- * The whole stack is then scaled by the non-gap fraction, which plain WebLogo
- * does not do. Here it earns its place: the track sits directly under an
- * alignment where the gaps are visible, and a column that is 90% gap drawing a
- * full-height stack off its one remaining pair of residues reads as a conserved
- * site. Scaling makes stack height mean "how much this column tells you about
- * the family", matching what the conservation track above it already plots.
+ * Unlike plain WebLogo, the stack is then scaled by the non-gap fraction, so a
+ * 90%-gap column with one conserved pair does not draw a full-height stack, and
+ * stack height matches the conservation track.
  */
 export function columnLogoStack(
   colStats: ColumnCounts,

package/src/stripDefault.ts

@@ -9,21 +9,14 @@ import type {
 /**
  * `types.stripDefault`, degrading to `types.optional` on hosts that lack it.
  *
- * stripDefault keeps defaulted properties out of snapshots, but it exists only
- * in the mobx-state-tree that ships with unreleased @jbrowse/core. This package
- * declares `@jbrowse/mobx-state-tree: ^5.0.0`, and inside jbrowse-web the host
- * supplies its own copy at runtime -- the plugin bundle externalizes it -- so we
- * genuinely do not know which version we are calling until we are running.
+ * stripDefault keeps defaulted properties out of snapshots, and only the
+ * mobx-state-tree in unreleased @jbrowse/core has it. The plugin bundle
+ * externalizes mobx-state-tree, so the host's copy is known only at runtime, and
+ * calling a missing stripDefault during model construction makes PluginLoader
+ * reject and the whole app show its error page.
  *
- * Calling it where it is absent throws while the model is being constructed,
- * which in a plugin bundle means PluginLoader rejects and the entire app renders
- * its error page. Losing minimal snapshots is a far better failure than losing
- * the session, so this degrades instead.
- *
- * The two signatures are identical, so behaviour differs only in that defaults
- * reappear in snapshots on older hosts (bigger session snapshots and shared
- * URLs, nothing incorrect). stripDefaultSnapshot.test.ts still pins the stripped
- * behaviour, since dev runs against a version that has it.
+ * The signatures are identical; on older hosts, defaults reappear in snapshots
+ * and shared URLs. stripDefaultSnapshot.test.ts pins the stripped behaviour.
  */
 export function stripDefault<IT extends IAnyType>(
   type: IT,

package/src/types.ts

@@ -1,3 +1,4 @@
+import type { ResolvedScale, ScaleSpec } from './scales.ts'
 import type { Annotation } from 'msa-parsers'
 
 export interface Accession {
@@ -5,17 +6,26 @@ export interface Accession {
   name: string
   description: string
 }
-// which renderer draws a track's content. Every track kind draws into the same
-// per-column coordinate space, so the kind picks the draw function rather than
-// the geometry -- see drawTracks.ts, which dispatches on it.
+// every kind draws into the same per-column space; drawTracks.ts dispatches on
+// it to pick the draw function
 export type TrackKind = 'text' | 'bar' | 'logo' | 'arc' | 'ruler'
 
+/**
+ * Which channel the color scheme paints. `fill` colors the cell a residue sits
+ * in, `color` colors the letter itself, the same distinction a grammar of
+ * graphics draws between a shape's interior and its own ink.
+ */
+export type ResidueEncoding = 'fill' | 'color'
+
 export interface BasicTrackModel {
   id: string
   name: string
   associatedRowName?: string
   height: number
   kind: TrackKind
+  // the model height this track's divider writes, shared with every track
+  // carrying the same key. Absent on a track no divider resizes.
+  heightKey?: string
   // hidden until the user asks for it, unless they have already chosen
   defaultOff?: boolean
 }
@@ -31,8 +41,8 @@ export interface BarTrackModel extends BasicTrackModel {
   barColor?: string
 }
 
-// a pair of columns joined by an arc, already resolved to 0-based visible
-// columns -- what the renderer consumes
+// a pair of columns joined by an arc, resolved to 0-based visible columns for
+// the renderer
 export interface Arc {
   start: number
   end: number
@@ -77,11 +87,108 @@ export interface ColumnTrackSpec {
   height?: number
 }
 
-// One contiguous run where a row's residues and a structure's line up 1:1.
-// Segment-shaped because SIFTS is: a dozen numbers cover what a per-residue
-// array would spend kilobytes on, and it makes the refusal rule structural
-// rather than a vocabulary -- a position no segment covers is unmapped, and
-// there is no status field to disagree with.
+/**
+ * A strip panel: one cell per row, colored from a `rowData` field through
+ * `scale`, which is ggtree's `gheatmap`. `width` is in pixels and defaults to
+ * the row height, and `header` labels the column and defaults to the field.
+ * `legend` titles the strip's legend and defaults to the field, and strips
+ * naming one title share one legend.
+ */
+export interface RowStripSpec {
+  kind: 'strip'
+  field: string
+  scale?: ScaleSpec
+  width?: number
+  header?: string
+  legend?: string
+}
+
+/** the channels a `features` panel reads off the feature table */
+export interface FeatureEncodingSpec {
+  color?: { field: string; scale?: ScaleSpec }
+  label?: string
+}
+
+/**
+ * Shifts each row so that the first feature named `on` starts at zero, which
+ * is gggenes' `make_alignment_dummies`. Only `x: "position"` reads it.
+ */
+export interface AlignTransform {
+  type: 'align'
+  on: string
+}
+
+/**
+ * A features panel: the GFF's spans per row, as arrows where they carry a
+ * strand. `x: "column"` draws them in the alignment's columns, and
+ * `x: "position"` in each row's own residue positions on one linear scale, so
+ * a genome with no alignment has an x.
+ */
+export interface RowFeaturesSpec {
+  kind: 'features'
+  x: 'column' | 'position'
+  width?: number
+  header?: string
+  encoding?: FeatureEncodingSpec
+  transform?: AlignTransform[]
+  /** how overlapping features share the row's height; see docs/layers.md */
+  position?: 'identity' | 'strandpile'
+}
+
+/**
+ * A panel left of the alignment on the row scale, the counterpart of
+ * ColumnTrackSpec on the column scale. See docs/layers.md
+ */
+export type RowPanelSpec = RowStripSpec | RowFeaturesSpec
+
+interface ResolvedPanelBase {
+  id: string
+  header: string
+  width: number
+  offsetX: number
+  legend: LegendEntry[]
+  /** the legend this panel's entries go under; absent means the domain key */
+  legendTitle?: string
+}
+
+/**
+ * A strip with its scale resolved: the color each row takes, keyed by row
+ * name, and the pixel column the panel draws in.
+ */
+export interface ResolvedStripPanel extends ResolvedPanelBase {
+  kind: 'strip'
+  field: string
+  colors: Map<string, string>
+}
+
+/** one feature of a features panel, at its pixel span inside the panel */
+export interface RowPanelSpan {
+  annotation: Annotation
+  xStart: number
+  xEnd: number
+  lane: number
+  laneCount: number
+}
+
+/**
+ * A features panel with its x mapping and its scale resolved: the spans per
+ * row name in panel pixels, the fill and outline of each feature, and the
+ * label its `label` channel draws. `field` is the field its color scale reads,
+ * which its legend is titled by.
+ */
+export interface ResolvedFeaturePanel extends ResolvedPanelBase {
+  kind: 'features'
+  x: 'column' | 'position'
+  field?: string
+  spans: Map<string, RowPanelSpan[]>
+  colors: Map<Annotation, { fill: string; stroke: string }>
+  labels?: Map<Annotation, string>
+}
+
+export type ResolvedRowPanel = ResolvedStripPanel | ResolvedFeaturePanel
+
+// One contiguous run where a row's residues and a structure's line up 1:1, as
+// SIFTS reports them. A position no segment covers is unmapped.
 export interface ResidueSegment {
   rowStart: number
   rowEnd: number
@@ -90,8 +197,8 @@ export interface ResidueSegment {
 }
 
 // the structure half of a mapping. `id` is whatever the producer calls the
-// entry (a PDB id, an AlphaFold accession); `asymId` names the chain, which is
-// what distinguishes two mappings onto the same entry
+// entry (a PDB id, an AlphaFold accession); `asymId` names the chain and
+// distinguishes two mappings onto the same entry
 export interface MappedStructure {
   id: string
   kind?: 'experimental' | 'predicted'
@@ -100,21 +207,16 @@ export interface MappedStructure {
 }
 
 /**
- * Which residue of which structure a row's residue is, as data. Computed by
- * whatever knows how -- SIFTS, an AlphaFold model, a curator -- and carried in
- * the snapshot, because the viewer cannot work it out: matching a row to a
- * structure by sequence equality fails for a construct with an expression tag,
- * a truncation, an engineered residue, or a row that is a subsequence of the
- * entry, and it fails in the direction that looks like it worked.
+ * The structure residue for each residue of a row, computed outside the viewer
+ * (SIFTS, an AlphaFold model, a curator). Sequence equality misplaces tagged
+ * constructs, truncations and subsequence rows; see docs/layers.md.
  *
  * Positions are 1-based and inclusive on both sides, as GFF and `highlights`
  * are. Structure positions are `label_seq_id`, the index into the entity's
- * SEQRES; author numbering carries insertion codes and stays out.
+ * SEQRES; author numbering carries insertion codes and is not used.
  *
  * `unobserved` is in structure positions: present in SEQRES with no
- * coordinates. Worth distinguishing from unmapped, because "the
- * crystallographer could not see it" and "this protein does not have that
- * residue" mean different things to a reader.
+ * coordinates, as distinct from a residue the structure lacks.
  */
 export interface ResidueMapping {
   row: string
@@ -123,11 +225,9 @@ export interface ResidueMapping {
   segments: ResidueSegment[]
   unobserved?: [number, number][]
   /**
-   * ungapped length of the row this was computed against. Optional, and worth
-   * setting: a mapping outlives the alignment it was made for, and pointing at
-   * residue 58 of a sequence that has since been re-aligned, revised or swapped
-   * is the failure this whole layer exists to avoid. Declared here, the viewer
-   * can notice and refuse instead of answering from stale arithmetic.
+   * ungapped length of the row this was computed against. When set, the viewer
+   * ignores the mapping if the loaded row's length differs, as it does after a
+   * re-alignment, revision or swapped sequence.
    */
   rowLength?: number
   generated?: {
@@ -137,25 +237,21 @@ export interface ResidueMapping {
   }
 }
 
-// why a mapping, or one segment of it, is not being used. Refusing silently
-// leaves a host unable to tell "no structure for this row" from "the mapping
-// no longer matches what is loaded", which are different problems with
-// different fixes.
+// why a mapping, or one segment of it, is ignored, so a host can tell "no
+// structure for this row" from "the mapping no longer matches what is loaded"
 export interface ResidueMappingProblem {
   row: string
   structureId: string
   /**
-   * `mapping` means the whole mapping is out: the evidence is about the row it
-   * claims, so nothing it says can be trusted. `segment` takes only that
-   * segment, since the rest of the mapping still describes residues that exist.
+   * `mapping` ignores the whole mapping, because the problem concerns its row.
+   * `segment` ignores only that segment and keeps the rest.
    */
   scope: 'mapping' | 'segment'
   reason: string
 }
 
-// what a lookup gives back: the structure residue a row residue is, or the row
-// residue a structure residue is. `observed` is false for a residue the
-// structure declares but did not resolve.
+// a lookup result in either direction. `observed` is false for a residue in
+// SEQRES with no coordinates.
 export interface StructureResidue {
   structure: MappedStructure
   position: number
@@ -168,29 +264,50 @@ export interface RowResidue {
 }
 
 /**
- * One loaded document that the snapshot leaves behind, and how big it is.
- * `what` names it the way the import form does, since that is where the reader
- * would go to load it differently.
+ * One loaded document that the snapshot omits, and its size. `what` uses the
+ * import form's names for the documents.
  */
 export interface UnshareableData {
   what: 'alignment' | 'tree' | 'annotations' | 'row metadata' | 'data tracks'
   bytes: number
 }
 
-// the overlay annotation itself lives in msa-parsers, alongside the adapters
-// that build it. TidyDomainAnnotation is its former name, kept because
-// downstream plugins name it in their emitted declarations.
+// Annotation is defined in msa-parsers. Downstream plugins' emitted
+// declarations still name TidyDomainAnnotation.
 export type { Annotation }
 export type TidyDomainAnnotation = Annotation
 
 // an annotation resolved to the visible column span it is drawn across.
-// stackIndex is its position among the bands its row actually draws, which the
-// sub-row layout uses to stack boxes.
+// stackIndex is its position in its row's paint order; lane is the sub-row it
+// occupies, out of the laneCount the row's overlaps need.
 export interface DomainBand {
   annotation: Annotation
   startCol: number
   endCol: number
   stackIndex: number
+  lane: number
+  laneCount: number
+}
+
+/**
+ * One swatch of a categorical color key. `id` is the value the scale read, and
+ * `label` is the text drawn beside the swatch.
+ */
+export interface LegendEntry {
+  id: string
+  label: string
+  color: string
+}
+
+/**
+ * A categorical color key, drawn by the on-screen overlay and reserved as a
+ * column in the SVG export. `title` names the legend where the viewer draws
+ * more than one.
+ */
+export interface Legend {
+  id: string
+  title: string
+  entries: LegendEntry[]
 }
 
 /**
@@ -207,6 +324,104 @@ export interface Highlight {
   color?: string
 }
 
+/**
+ * What the viewer draws over a clade. `highlight` fills the rows behind it,
+ * across the tree and the alignment. `bracket` draws a bar and the clade's
+ * `label` in the gutter right of the tip labels. `collapse` and `focus` seed
+ * the collapsed list and the subtree in focus at load.
+ */
+export type CladeMark = 'highlight' | 'bracket' | 'collapse' | 'focus'
+
+/**
+ * A clade of the tree and the mark drawn over it. `mrca` names tips whose most
+ * recent common ancestor is the clade; `range` names the first and last tip of
+ * a run in display order, in either order. `tips` is the leaf count the
+ * producer measured, and a clade that resolves to a different count is dropped.
+ * `label` names the clade beside a bracket, and a highlight carrying one draws
+ * the label without the bar. See docs/layers.md
+ */
+export interface Clade {
+  mrca?: string[]
+  range?: [string, string]
+  tips: number
+  mark: CladeMark
+  color?: string
+  label?: string
+}
+
+/**
+ * A Clade resolved to the rows it covers, with its fill color settled. `color`
+ * is the highlight fill; `markColor` is the producer's own color for a bracket
+ * bar and its label, unset where the theme's text color stands. `nodeId` is the
+ * node an `mrca` resolved to, which `collapse` and `focus` seed themselves
+ * with, and a `range` record has none.
+ */
+export interface ResolvedClade {
+  rows: [number, number]
+  mark: CladeMark
+  color: string
+  markColor?: string
+  label?: string
+  nodeId?: string
+}
+
+/**
+ * A span in Highlight coordinates: 1-based inclusive residues of `row`, or
+ * columns of the file without it
+ */
+export interface Region {
+  row?: string
+  start: number
+  end: number
+}
+
+/**
+ * A cell of the alignment in the host's coordinates, 1-based like Highlight:
+ * `column` counts every column of the file, hidden gappy ones included, and
+ * `residue` counts the row's own letters, absent on a gap. A pointer over a
+ * track has a column and no row.
+ */
+export interface Cell {
+  column: number
+  row?: string
+  residue?: number
+  letter?: string
+}
+
+/** the alignment columns on screen, 1-based and inclusive */
+export interface Viewport {
+  startColumn: number
+  endColumn: number
+}
+
+/**
+ * A channel of a mark the viewer always draws. `tipLabel` colors each tip label
+ * in the tree, `rowTint` washes the row across the tree gutter and the
+ * alignment, and `branch` colors a tree edge whose tips all share one value;
+ * all three read a field of `rowData`. `featureFill` colors each span of the
+ * annotation overlay and `featureLabel` names the field drawn inside a span,
+ * both from a field of the feature table.
+ */
+export type EncodingChannel =
+  | 'tipLabel'
+  | 'rowTint'
+  | 'branch'
+  | 'featureFill'
+  | 'featureLabel'
+
+/**
+ * A channel, the field feeding it, and the scale it reads that field through.
+ * See docs/layers.md
+ */
+export interface Encoding {
+  channel: EncodingChannel
+  field: string
+  scale?: ScaleSpec
+}
+
+/** an Encoding with its scale resolved against the values in the table */
+export type ResolvedEncoding = Encoding & ResolvedScale
+
 /** a Highlight resolved to visible column indices and row indices */
 export interface ResolvedHighlight {
   startCol?: number

package/src/umd.ts

@@ -1,9 +1,11 @@
 import * as React from 'react'
 
-// a host that swaps models (the R htmlwidget on re-render) has to destroy the
-// old one, or the disposers its autoruns registered never run
+// a page that builds models with MSAModelF destroys each one it replaces, so
+// the disposers its autoruns registered run
 export { destroy } from '@jbrowse/mobx-state-tree'
 export { default as MSAView } from './components/Loading.tsx'
+export { mount } from './mount.tsx'
+export { defineMsaElement } from './element.ts'
 export { type MsaViewModel, default as MSAModelF } from './model.ts'
 
 export * from 'react-dom/client'

package/src/useCanvasAutorun.ts

@@ -6,17 +6,12 @@ import type React from 'react'
 
 /**
  * Wires a canvas ref to a mobx autorun: grabs the 2d context once the canvas
- * mounts and re-runs `draw` whenever any observable it reads changes. Collapses
- * the getContext/null-guard/autorun-dispose boilerplate repeated by every canvas
- * block host.
+ * mounts and re-runs `draw` whenever any observable it reads changes.
  *
- * `width`/`height` are the canvas *backing store* size the caller renders onto
- * the element (logical size times the high-res scale factor), and they are load
- * bearing rather than informational. Assigning either resets the canvas bitmap,
- * and React assigns them on every commit where they changed -- which lands
- * *after* the mobx reaction that already redrew at the old size. Without a redraw
- * on the far side of that commit the canvas is left blank: it is what blanked the
- * tree on a tree-area resize and the consensus tracks on a vertical zoom.
+ * `width`/`height` are the canvas backing store size (logical size times the
+ * high-res scale factor). Assigning either clears the bitmap, and React assigns
+ * them after the mobx reaction has drawn at the old size, so the effect redraws
+ * when they change.
  *
  * `deps` covers everything else the effect should re-subscribe on, matching a
  * normal useEffect dep array.

package/src/useMsaSvgFigure.ts

@@ -0,0 +1,72 @@
+import { useEffect, useState } from 'react'
+
+import { createJBrowseTheme } from '@jbrowse/core/ui/theme'
+import { getSnapshot } from '@jbrowse/mobx-state-tree'
+import { compareStructural, reaction } from 'mobx'
+
+import { renderToSvg } from './renderToSvg.tsx'
+
+import type { MsaViewModel } from './model.ts'
+import type { Theme } from '@mui/material'
+
+export interface MsaSvgFigure {
+  /** the SVG document for what is on screen, once the first draw finishes */
+  svg?: string
+  error?: unknown
+}
+
+/**
+ * The viewer's SVG export of its viewport, as markup for the page to insert.
+ * It redraws after the view settles: `delay` ms after the last scroll, zoom,
+ * resize or change to the snapshot. A draw a later one overtakes is dropped.
+ *
+ * The figure's row names and letters are SVG text, so the browser's find
+ * locates them, a reader can select them, and print stylesheets apply.
+ */
+export function useMsaSvgFigure(
+  model: MsaViewModel,
+  {
+    theme,
+    includeTracks = false,
+    delay = 300,
+  }: { theme?: Theme; includeTracks?: boolean; delay?: number } = {},
+) {
+  const [figure, setFigure] = useState<MsaSvgFigure>({})
+  useEffect(() => {
+    let latest = 0
+    const dispose = reaction(
+      () =>
+        model.viewInitialized && model.dataInitialized
+          ? [getSnapshot(model), model.width, model.height]
+          : undefined,
+      key => {
+        if (!key) {
+          return
+        }
+        const draw = ++latest
+        renderToSvg(model, {
+          theme: theme ?? createJBrowseTheme(),
+          exportType: 'viewport',
+          includeTracks,
+        }).then(
+          svg => {
+            if (draw === latest) {
+              setFigure({ svg })
+            }
+          },
+          (error: unknown) => {
+            if (draw === latest) {
+              setFigure({ error })
+            }
+          },
+        )
+      },
+      { delay, fireImmediately: true, equals: compareStructural },
+    )
+    return () => {
+      latest = -1
+      dispose()
+    }
+  }, [model, theme, includeTracks, delay])
+  return figure
+}

package/src/useWheelScroll.ts

@@ -147,10 +147,6 @@ export function useWheelScroll({
   }, [mouseDragging, onScrollX, onScrollY])
 
   function onMouseDown(event: React.MouseEvent) {
-    const target = event.target as HTMLElement
-    if (target.draggable || target.dataset.resizer) {
-      return
-    }
     if (event.button === 0) {
       prevX.current = event.clientX
       prevY.current = event.clientY