react-msaview 6.5.0 → 8.0.0

package/src/components/tree/renderTreeOverview.ts

@@ -0,0 +1,212 @@
+import { descendants } from '../../hierarchy.ts'
+import { getNodeX } from './renderTreeCanvas.ts'
+
+import type { HierarchyNode } from '../../hierarchy.ts'
+import type { MsaViewModel } from '../../model.ts'
+import type { RasterCanvas } from '../msa/msaRaster.ts'
+import type { RenderCtx } from '../renderCtx.ts'
+import type { Theme } from '@mui/material'
+
+// the tree draws this far inside the band, so a box around the first or the
+// last row keeps both of its edges
+const pad = 1
+
+interface OverviewArgs {
+  model: MsaViewModel
+  ctx: RenderCtx
+  theme: Theme
+  width: number
+  height: number
+}
+
+function rowScale(numTips: number, height: number) {
+  const inner = height - pad * 2
+  return (row: number) => pad + (row / numTips) * inner
+}
+
+/**
+ * The whole tree at the size of the overview band, with the clade highlights
+ * under it.
+ *
+ * A branch that moves less than a pixel on both axes is dropped. The 230k-tip
+ * COVID tree has 460k of them over a 120px band, and the ones landing on the
+ * pixel their parent already covers cost a path segment each and change no
+ * pixel; the test in renderTreeOverview.test.ts measures a 200k-tip tree.
+ */
+export function drawTreeOverview({
+  model,
+  ctx,
+  theme,
+  width,
+  height,
+}: OverviewArgs) {
+  const layout = model.treeOverviewLayout
+  if (!layout) {
+    return
+  }
+  const { root, numTips, maxDepthToLeaf, showBranchLen } = layout
+  const innerWidth = width - pad * 2
+  const rowY = rowScale(numTips, height)
+  const nodeX = (node: HierarchyNode) =>
+    pad + (getNodeX(node, showBranchLen, 1, maxDepthToLeaf) ?? 0) * innerWidth
+
+  for (const { rows, color } of model.treeOverviewClades) {
+    ctx.fillStyle = color
+    ctx.fillRect(0, rowY(rows[0]), width, rowY(rows[1] + 1) - rowY(rows[0]))
+  }
+
+  ctx.strokeStyle = theme.palette.text.primary
+  ctx.beginPath()
+  for (const source of descendants(root)) {
+    if (!source.children) {
+      continue
+    }
+    const sx = nodeX(source)
+    const sy = rowY(source.x!)
+    for (const target of source.children) {
+      const tx = nodeX(target)
+      const ty = rowY(target.x!)
+      if (Math.abs(tx - sx) < 1 && Math.abs(ty - sy) < 1) {
+        continue
+      }
+      ctx.moveTo(sx, sy)
+      ctx.lineTo(sx, ty)
+      ctx.lineTo(tx, ty)
+    }
+  }
+  ctx.stroke()
+}
+
+/**
+ * A box across the overview around a run of tip rows: the focused subtree's
+ * extent, or the one a hovered pixel would focus.
+ */
+export function drawTreeOverviewBox({
+  model,
+  ctx,
+  color,
+  rows,
+  width,
+  height,
+}: Omit<OverviewArgs, 'theme'> & {
+  color: string
+  rows: [number, number]
+}) {
+  const layout = model.treeOverviewLayout
+  if (!layout) {
+    return
+  }
+  const rowY = rowScale(layout.numTips, height)
+  const top = rowY(rows[0])
+  ctx.strokeStyle = color
+  ctx.strokeRect(0.5, top, width - 1, Math.max(2, rowY(rows[1] + 1) - top))
+}
+
+/**
+ * The overview as the figure carries it: the tree, the clade highlights and
+ * the focus box. The SVG export draws it straight onto a svgcanvas Context,
+ * and the live canvas blits `treeOverviewImage` in place of the first two.
+ */
+export function renderTreeOverview(args: OverviewArgs) {
+  drawTreeOverview(args)
+  const rows = args.model.treeOverviewFocusRows
+  if (rows) {
+    drawTreeOverviewBox({
+      ...args,
+      rows,
+      color: args.theme.palette.text.primary,
+    })
+  }
+}
+
+interface OverviewCache {
+  keys: unknown[]
+  canvas: RasterCanvas | undefined
+}
+
+const caches = new WeakMap<object, OverviewCache>()
+
+/**
+ * Everything the drawn tree depends on. `treeOverviewLayout` and
+ * `treeOverviewClades` are computed views, which recompute on every read
+ * outside a reaction, so the key holds the values behind them instead.
+ */
+function overviewKeys({
+  model,
+  theme,
+  width,
+  height,
+  scale,
+}: {
+  model: MsaViewModel
+  theme: Theme
+  width: number
+  height: number
+  scale: number
+}) {
+  return [
+    model.data.tree,
+    model.data.msa,
+    model.currentAlignment,
+    model.collapsed.join(','),
+    JSON.stringify(model.clades),
+    model.showBranchLen,
+    width,
+    height,
+    scale,
+    theme.palette.text.primary,
+  ]
+}
+
+function makeCanvas(width: number, height: number) {
+  const canvas =
+    typeof OffscreenCanvas !== 'undefined'
+      ? new OffscreenCanvas(width, height)
+      : typeof document !== 'undefined'
+        ? Object.assign(document.createElement('canvas'), { width, height })
+        : undefined
+  const ctx = canvas?.getContext('2d')
+  return ctx && typeof (ctx as CanvasRenderingContext2D).stroke === 'function'
+    ? { canvas: canvas as RasterCanvas, ctx: ctx as CanvasRenderingContext2D }
+    : undefined
+}
+
+/**
+ * The tree and its clade highlights on an offscreen canvas, drawn once per
+ * change of anything they depend on and blitted every frame after that. A
+ * 230k-branch tree takes hundreds of milliseconds to walk and cannot be redrawn
+ * as the focus box follows the pointer.
+ *
+ * Returns undefined where a canvas has no 2d context (jsdom), and the caller
+ * then draws the tree itself.
+ */
+export function treeOverviewImage({
+  model,
+  theme,
+  width,
+  height,
+  scale,
+}: {
+  model: MsaViewModel
+  theme: Theme
+  width: number
+  height: number
+  scale: number
+}) {
+  const keys = overviewKeys({ model, theme, width, height, scale })
+  const prev = caches.get(model)
+  if (prev && keys.every((key, i) => key === prev.keys[i])) {
+    return prev.canvas
+  }
+  const made = makeCanvas(
+    Math.max(1, Math.round(width * scale)),
+    Math.max(1, Math.round(height * scale)),
+  )
+  if (made) {
+    made.ctx.scale(scale, scale)
+    drawTreeOverview({ model, ctx: made.ctx, theme, width, height })
+  }
+  const next = { keys, canvas: made?.canvas }
+  caches.set(model, next)
+  return next.canvas
+}

package/src/components/tree/scaleBar.ts

@@ -0,0 +1,23 @@
+/**
+ * A round branch-length step and its width in pixels: the largest 1/2/5 x 10^n
+ * substitutions-per-site that fits in `maxPx`, aiming at about half of it.
+ * Returns undefined in cladogram mode, where the x-positions carry no length.
+ */
+export function scaleBarLength(pxPerUnit: number, maxPx: number) {
+  if (pxPerUnit <= 0 || maxPx < 20) {
+    return undefined
+  }
+  const target = maxPx / 2 / pxPerUnit
+  const magnitude = 10 ** Math.floor(Math.log10(target))
+  const mantissa = target / magnitude
+  const step = (mantissa >= 5 ? 5 : mantissa >= 2 ? 2 : 1) * magnitude
+  const px = step * pxPerUnit
+  return px > maxPx
+    ? undefined
+    : {
+        step,
+        px,
+        // a length of 0.02 reads as 0.02, not 0.020000000000000004
+        label: `${Number(step.toPrecision(2))}`,
+      }
+}

package/src/components/tree/useTreeHover.ts

@@ -1,4 +1,4 @@
-import { useRef, useState } from 'react'
+import { useState } from 'react'
 
 import { ClickMapIndex } from './clickMap.ts'
 
@@ -24,9 +24,7 @@ export function useTreeHover({
   model: MsaViewModel
   offsetY: number
 }) {
-  const clickMapRef = useRef<ClickMapIndex>(null)
-  clickMapRef.current ??= new ClickMapIndex()
-  const clickMap = clickMapRef.current
+  const [clickMap] = useState(() => new ClickMapIndex())
   const [hovered, setHovered] = useState<TreeHoverTarget>()
 
   // leaf labels win over the branch/bubble targets they overlap, so a click on a

package/src/constants.ts

@@ -5,18 +5,22 @@ export const defaultHeight = 550
 export const defaultScrollX = 0
 export const defaultScrollY = 0
 export const defaultCurrentAlignment = 0
-export const defaultShowDomains = false
+// Only a hidden overlay is stored, so a link that never mentions it opens
+// showing its annotations.
+export const defaultShowDomains = true
 export const defaultShowDomainLegend = true
 export const defaultHideGaps = true
 export const defaultAllowedGappyness = 100
 export const defaultSubFeatureRows = false
-// row height for each stacked feature when subFeatureRows is on
+// height of one sub-row when subFeatureRows is on, unless the row has more
+// lanes than fit at this height (see renderBoxFeatureCanvasBlock)
 export const subFeatureRowHeight = 4
+// height of the bar the overlay draws under a row in letter-color mode
+export const domainUnderlineHeight = 3
 
-// Feature types that are ordinal *segments* of a single transcript (exons and
-// the like) rather than categorical domains. Their identity is their position,
-// so the overlay alternates two shades to mark boundaries and labels them by
-// number, instead of assigning every one a distinct hue + legend row.
+// Feature types that are ordinal segments of one transcript. The overlay
+// alternates two shades across them and labels them by number, where a domain
+// type gets its own hue and legend row.
 export const segmentFeatureTypes = new Set([
   'exon',
   'CDS',
@@ -31,9 +35,16 @@ export const segmentShades = ['#9fb6d4', '#d4dcea']
 export const defaultDrawMsaLetters = true
 export const defaultScrollZoom = false
 
+// Which cell dimensions a wheel zoom scales. 'horizontal' holds the row height,
+// which fixes the label and letter font size while the columns compress.
+// 'vertical' does the reverse.
+export const scrollZoomAxes = ['both', 'horizontal', 'vertical'] as const
+export type ScrollZoomAxis = (typeof scrollZoomAxes)[number]
+export const defaultScrollZoomAxis: ScrollZoomAxis = 'both'
+
 // Cell size floors for drawing residue letters and tree labels. Below these a
-// 500px block holds thousands of glyphs, and fillText -- which no sprite atlas
-// beats, measured -- dominates every zoom frame.
+// 500px block holds thousands of glyphs, and fillText dominates every zoom
+// frame. A sprite atlas measured slower.
 export const minLetterRowHeight = 8
 export const minLetterColWidth = 5
 
@@ -61,3 +72,45 @@ export const defaultTreeWidth = 300
 export const defaultShowBranchLen = true
 export const defaultDrawTree = true
 export const defaultDrawNodeBubbles = true
+export const defaultDrawNodeLabels = false
+export const defaultShowTreeOverview = false
+export const defaultOverviewHeight = 120
+
+// Neighbor joining does not run above this many rows. The distance matrix is
+// O(n^2*L) and the join loop O(n^3), both on the main thread with no progress
+// and no cancel: 400 rows measured 1.5s, 800 rows 10s, and 1600 would be about
+// seventy. See agent-docs/ideas/neighbor-joining-scaling.md.
+export const maxNeighborJoiningRows = 500
+
+// The opacity a `rowTint` encoding draws its scale's color at, so the residues
+// under the wash stay readable. A color the producer already gave an alpha
+// keeps it.
+export const rowTintAlpha = 0.25
+
+// The fill a `clades` record with the `highlight` mark draws behind its rows,
+// and the opacity a producer's own color takes when it carries none.
+export const cladeHighlightColor = '#fff3c4'
+export const cladeHighlightAlpha = 0.6
+
+// The largest inline document the snapshot carries. A larger pasted or
+// locally-opened file stays in the live model and out of the snapshot, keeping
+// shared URLs sendable. `unshareableData` warns using the same number.
+export const maxInlineSnapshotBytes = 50_000
+
+// Height of the band the `rowPanels` headers draw in, above the strips in the
+// top area beside the tree ruler and the minimap. A panel wider than the band
+// is tall writes its header across, where it has more room.
+export const rowPanelHeaderHeight = 56
+
+// Height of the branch-length scale bar above the tree.
+export const treeScaleBarHeight = 22
+
+// Width of a `features` row panel that names none, wide enough for a gene
+// neighborhood of a few arrows to read.
+export const defaultFeaturePanelWidth = 200
+
+// The alignment's overlay canvas draws the mouseover, the persisted highlights
+// and the row tints over the residues, and the legend key floats above that,
+// so a tint reaching the top right corner leaves the key readable.
+export const msaOverlayZIndex = 1000
+export const legendZIndex = msaOverlayZIndex + 1

package/src/createPaletteMap.ts

@@ -3,17 +3,18 @@ import { colord } from 'colord'
 import palettes from './ggplotPalettes.ts'
 
 /**
- * Creates a map from keys to colors. Up to the largest ggplot palette (8 keys)
- * we use the hand-picked ggplot colors; beyond that — e.g. a gene-structure
- * overlay with one feature per exon — we generate evenly spaced HSL hues so
- * every key still gets a distinct, stable color instead of running off the end
- * of the palette.
+ * Creates a map from keys to colors. `palette` names the colors to take in
+ * order, such as the list a scale asked for by name; without it the keys take
+ * the ggplot palette of their own size. Beyond the colors available — a
+ * gene-structure overlay with one feature per exon, or nine keys on an
+ * eight-color palette — every key gets an evenly spaced HSL hue instead, so no
+ * two keys share a color.
  */
-export function createPaletteMap(keys: string[]) {
+export function createPaletteMap(keys: string[], palette?: readonly string[]) {
   const n = keys.length
-  if (n <= palettes.length) {
-    const palette = palettes[n - 1]!
-    return Object.fromEntries(keys.map((key, i) => [key, palette[i]!]))
+  const colors = palette ?? palettes[n - 1]
+  if (colors && n <= colors.length) {
+    return Object.fromEntries(keys.map((key, i) => [key, colors[i]!]))
   }
   return Object.fromEntries(
     keys.map((key, i) => [

package/src/element.ts

@@ -0,0 +1,321 @@
+import { when } from 'mobx'
+
+import { mount } from './mount.tsx'
+
+import type { MSAViewerProps } from './components/MSAViewer.tsx'
+import type { MsaViewModel } from './model.ts'
+import type { MountedViewer } from './mount.tsx'
+import type {
+  Cell,
+  ColumnTrackSpec,
+  Highlight,
+  ResidueMapping,
+  Viewport,
+} from './types.ts'
+
+type ElementData = Pick<
+  MSAViewerProps,
+  'msa' | 'tree' | 'gff' | 'highlights' | 'columnTracks' | 'residueMappings'
+>
+
+interface NightingaleManager extends HTMLElement {
+  register: (element: HTMLElement) => void
+  unregister: (element: HTMLElement) => void
+}
+
+const ownAttributes = [
+  'msa-url',
+  'tree-url',
+  'gff-url',
+  'color-scheme',
+  'height',
+  'hide-header',
+  'theme',
+  'reference-row',
+  'tree-area-width',
+] as const
+
+// the attributes a <nightingale-manager> writes on the elements it holds
+const nightingaleAttributes = ['display-start', 'display-end', 'highlight']
+
+function location(uri: string | null) {
+  return uri ? { uri, locationType: 'UriLocation' as const } : undefined
+}
+
+function numberAttribute(value: string | null | undefined) {
+  const n = value ? Number(value) : Number.NaN
+  return Number.isFinite(n) ? n : undefined
+}
+
+// Nightingale writes a highlight as "start:end,start:end", 1-based inclusive
+function parseHighlight(value: string | null, row?: string): Highlight[] {
+  return (value ?? '').split(',').flatMap(span => {
+    const [start, end] = span.split(':').map(numberAttribute)
+    return start === undefined ? [] : [{ row, start, end: end ?? start }]
+  })
+}
+
+function residueAtColumn(model: MsaViewModel, row: string, column: number) {
+  const visible = model.globalColToVisibleCol(column - 1)
+  return visible === undefined
+    ? undefined
+    : model.visibleColToSeqPosOneBased(row, visible)
+}
+
+// the first and last residues of `row` inside the viewport's columns
+function residueRange(model: MsaViewModel, row: string, viewport: Viewport) {
+  let start: number | undefined
+  let end: number | undefined
+  for (let c = viewport.startColumn; c <= viewport.endColumn && !start; c++) {
+    start = residueAtColumn(model, row, c)
+  }
+  for (let c = viewport.endColumn; c >= viewport.startColumn && !end; c--) {
+    end = residueAtColumn(model, row, c)
+  }
+  return start && end ? { start, end } : undefined
+}
+
+/**
+ * Registers a custom element that renders MSAViewer, for pages with no React.
+ * Attributes: msa-url, tree-url, gff-url, color-scheme, height, hide-header,
+ * theme, tree-area-width and reference-row. Properties: msa, tree and gff text, highlights,
+ * columnTracks and residueMappings. Events: cell-hover, cell-click and
+ * viewport-change, each with the MSAViewer callback's value as detail.
+ *
+ * Inside a <nightingale-manager>, the element registers with it and speaks its
+ * protocol: it follows the display-start, display-end and highlight attributes
+ * the manager writes, and reports its own range and hovered residue as change
+ * events. Positions are residues of reference-row, or columns without one.
+ */
+export function defineMsaElement(tagName = 'jbrowse-msa') {
+  const existing = customElements.get(tagName)
+  if (existing) {
+    return existing
+  }
+
+  class MsaElement extends HTMLElement {
+    static observedAttributes = [...ownAttributes, ...nightingaleAttributes]
+
+    #viewer?: MountedViewer
+    #model?: MsaViewModel
+    #manager?: NightingaleManager
+    #cancelRange?: () => void
+    #rangePending = false
+    #reported?: { start: number; end: number }
+    #data: ElementData = {}
+
+    get msa() {
+      return this.#data.msa
+    }
+    set msa(value: string | undefined) {
+      this.#setData({ msa: value })
+    }
+    get tree() {
+      return this.#data.tree
+    }
+    set tree(value: string | undefined) {
+      this.#setData({ tree: value })
+    }
+    get gff() {
+      return this.#data.gff
+    }
+    set gff(value: string | undefined) {
+      this.#setData({ gff: value })
+    }
+    get highlights() {
+      return this.#data.highlights
+    }
+    set highlights(value: Highlight[] | undefined) {
+      this.#setData({ highlights: value })
+    }
+    get columnTracks() {
+      return this.#data.columnTracks
+    }
+    set columnTracks(value: ColumnTrackSpec[] | undefined) {
+      this.#setData({ columnTracks: value })
+    }
+    get residueMappings() {
+      return this.#data.residueMappings
+    }
+    set residueMappings(value: ResidueMapping[] | undefined) {
+      this.#setData({ residueMappings: value })
+    }
+
+    get #referenceRow() {
+      return this.getAttribute('reference-row') ?? undefined
+    }
+
+    #setData(data: ElementData) {
+      this.#data = { ...this.#data, ...data }
+      this.#viewer?.update(this.#props())
+    }
+
+    #props(): MSAViewerProps {
+      const theme = this.getAttribute('theme')
+      return {
+        ...this.#data,
+        msaFilehandle: location(this.getAttribute('msa-url')),
+        treeFilehandle: location(this.getAttribute('tree-url')),
+        gffFilehandle: location(this.getAttribute('gff-url')),
+        colorScheme: this.getAttribute('color-scheme') ?? undefined,
+        height: numberAttribute(this.getAttribute('height')),
+        treeAreaWidth: numberAttribute(this.getAttribute('tree-area-width')),
+        hideHeader: this.hasAttribute('hide-header'),
+        theme: theme === 'dark' ? 'dark' : 'light',
+        onCellHover: cell => {
+          this.#emit('cell-hover', cell)
+          this.#reportHover(cell)
+        },
+        onCellClick: cell => {
+          this.#emit('cell-click', cell)
+        },
+        onViewportChange: viewport => {
+          this.#emit('viewport-change', viewport)
+          this.#reportRange(viewport)
+        },
+        onModel: model => {
+          this.#model = model
+          this.#followRange()
+          this.#followHighlight()
+        },
+      }
+    }
+
+    #emit(type: string, detail: unknown) {
+      this.dispatchEvent(new CustomEvent(type, { detail }))
+    }
+
+    #nightingaleChange(detail: Record<string, unknown>) {
+      if (this.#manager) {
+        this.dispatchEvent(
+          new CustomEvent('change', {
+            detail,
+            bubbles: true,
+            cancelable: true,
+          }),
+        )
+      }
+    }
+
+    #reportHover(cell: Cell | undefined) {
+      const model = this.#model
+      const row = this.#referenceRow
+      const position =
+        cell && model && row
+          ? residueAtColumn(model, row, cell.column)
+          : cell?.column
+      this.#nightingaleChange({
+        type: 'highlight',
+        value: position === undefined ? null : `${position}:${position}`,
+      })
+    }
+
+    #reportRange(viewport: Viewport | undefined) {
+      const model = this.#model
+      const row = this.#referenceRow
+      if (!viewport || !model) {
+        return
+      }
+      const range = row
+        ? residueRange(model, row, viewport)
+        : { start: viewport.startColumn, end: viewport.endColumn }
+      const shownStart = numberAttribute(this.getAttribute('display-start'))
+      const shownEnd = numberAttribute(this.getAttribute('display-end'))
+      // a range the manager just wrote comes back within a column of itself,
+      // since the viewer shows whole columns
+      const echo =
+        range &&
+        shownStart !== undefined &&
+        shownEnd !== undefined &&
+        Math.abs(range.start - shownStart) <= 1 &&
+        Math.abs(range.end - shownEnd) <= 1
+      if (range && !echo) {
+        this.#reported = range
+        this.#nightingaleChange({
+          'display-start': range.start,
+          'display-end': range.end,
+        })
+      }
+    }
+
+    #followRange() {
+      const model = this.#model
+      const start = numberAttribute(this.getAttribute('display-start'))
+      const end = numberAttribute(this.getAttribute('display-end'))
+      const reported = this.#reported
+      // the manager writes the range this element reported back onto it, and
+      // zooming to it again would snap the reader's own zoom to whole residues
+      if (reported && reported.start === start && reported.end === end) {
+        return
+      }
+      this.#cancelRange?.()
+      if (model && start !== undefined && end !== undefined) {
+        const row = this.#referenceRow
+        this.#cancelRange = when(
+          () => model.viewInitialized && model.numColumns > 0,
+          () => {
+            model.zoomToRegion({ row, start, end })
+          },
+        )
+      }
+    }
+
+    #followHighlight() {
+      const spans = parseHighlight(
+        this.getAttribute('highlight'),
+        this.#referenceRow,
+      )
+      if (spans.length) {
+        this.#model?.applyHighlight('nightingale', spans)
+      } else {
+        this.#model?.clearHighlight('nightingale')
+      }
+    }
+
+    connectedCallback() {
+      if (!this.style.display) {
+        this.style.display = 'block'
+      }
+      this.#viewer = mount(this, this.#props())
+      const manager = this.closest<NightingaleManager>('nightingale-manager')
+      if (manager) {
+        void customElements.whenDefined('nightingale-manager').then(() => {
+          if (this.isConnected) {
+            this.#manager = manager
+            manager.register(this)
+          }
+        })
+      }
+    }
+
+    disconnectedCallback() {
+      this.#manager?.unregister(this)
+      this.#manager = undefined
+      this.#cancelRange?.()
+      this.#viewer?.destroy()
+      this.#viewer = undefined
+      this.#model = undefined
+    }
+
+    attributeChangedCallback(name: string) {
+      if (name === 'display-start' || name === 'display-end') {
+        // the manager writes the two attributes one after the other, and a
+        // zoom between them reports a range that overwrites the second
+        if (!this.#rangePending) {
+          this.#rangePending = true
+          queueMicrotask(() => {
+            this.#rangePending = false
+            this.#followRange()
+          })
+        }
+      } else if (name === 'highlight') {
+        this.#followHighlight()
+      } else {
+        this.#viewer?.update(this.#props())
+      }
+    }
+  }
+
+  customElements.define(tagName, MsaElement)
+  return MsaElement
+}