react-msaview 9.0.0 → 9.1.1

package/src/featurePanels.ts

@@ -0,0 +1,269 @@
+import { notEmpty } from '@jbrowse/core/util'
+
+import { packDomainLanes } from './components/msa/packDomainLanes.ts'
+import { defaultFeaturePanelWidth } from './constants.ts'
+import { featureField } from './featureFields.ts'
+import { resolveScale } from './scales.ts'
+import { outlineColor } from './util.ts'
+
+import type { ScaleSpec } from './scales.ts'
+import type {
+  Annotation,
+  DomainBand,
+  RowFeaturesSpec,
+  RowPanelSpan,
+  RowPanelSpec,
+} from './types.ts'
+
+// the fill of a span under a scale that gives its value no color, such as a
+// gene a `map` over gene names leaves out
+const UNSCALED_FEATURE = '#d9d9d9'
+
+// the fraction of a span a following one may cover before it takes a lane of
+// its own in a `features` panel
+const laneOverlap = 0.1
+
+// a row panel's own width, or a default: the row height, which makes a strip
+// cell square, and a gene neighborhood's width for a features panel. The row
+// height is read only when used, so a panel with a width of its own does not
+// recompute on a vertical zoom
+export function rowPanelWidth(
+  panel: RowPanelSpec,
+  view: { rowHeight: number },
+) {
+  return (
+    panel.width ??
+    (panel.kind === 'features' ? defaultFeaturePanelWidth : view.rowHeight)
+  )
+}
+
+// one row of the row table as the channels read it. A number or a boolean
+// reads as its string, the way a GFF value does, and null or an object drops
+export function stringFields(row: unknown) {
+  if (typeof row !== 'object' || row === null) {
+    return undefined
+  }
+  const fields: Record<string, string> = {}
+  for (const [field, value] of Object.entries(row)) {
+    if (typeof value === 'string') {
+      fields[field] = value
+    } else if (typeof value === 'number' || typeof value === 'boolean') {
+      fields[field] = String(value)
+    }
+  }
+  return fields
+}
+
+// the color each row takes from a field of the row table under a scale
+export function colorByRow(
+  rowData: Record<string, Record<string, string> | undefined>,
+  field: string,
+  colorOf: (value: string) => string | undefined,
+) {
+  const colors = new Map<string, string>()
+  for (const [name, row] of Object.entries(rowData)) {
+    const value = row?.[field]
+    const color = value === undefined ? undefined : colorOf(value)
+    if (color) {
+      colors.set(name, color)
+    }
+  }
+  return colors
+}
+
+// the fill and outline of every feature in a list: its own GFF `color=` first,
+// then the scale an encoding resolves over one of its fields, then the
+// accession palette
+export function featureColorMap(
+  annotations: Annotation[],
+  encoding:
+    | { field: string; colorOf: (value: string) => string | undefined }
+    | undefined,
+  fillPalette: Record<string, string>,
+) {
+  const strokes = new Map<string, string>()
+  const strokeOf = (fill: string) => {
+    const hit = strokes.get(fill)
+    if (hit !== undefined) {
+      return hit
+    }
+    const stroke = outlineColor(fill)
+    strokes.set(fill, stroke)
+    return stroke
+  }
+  return new Map(
+    annotations.map(annotation => {
+      const value = encoding
+        ? featureField(annotation, encoding.field)
+        : undefined
+      const fill =
+        annotation.color ??
+        (value === undefined ? undefined : encoding!.colorOf(value)) ??
+        (encoding ? UNSCALED_FEATURE : fillPalette[annotation.accession]!)
+      return [annotation, { fill, stroke: strokeOf(fill) }]
+    }),
+  )
+}
+
+// the text a label channel draws inside each span, for the features carrying
+// the field it names
+export function featureLabelMap(annotations: Annotation[], field: string) {
+  const labels = new Map<Annotation, string>()
+  for (const annotation of annotations) {
+    const value = featureField(annotation, field)
+    if (value !== undefined) {
+      labels.set(annotation, value)
+    }
+  }
+  return labels
+}
+
+/** what `packDomainLanes` needs to lay a row out, before it has its lane */
+type Unlaned = Omit<RowPanelSpan, 'lane' | 'laneCount'> & {
+  startCol: number
+  endCol: number
+}
+
+/**
+ * Lanes for `position: "strandpile"`, gggenomes' `position_strandpile`: the
+ * forward features stack above the line and the reverse below it, each strand
+ * packing on its own. The deepest row on each side sets the grid every row lays
+ * out on, so the line between the strands sits at one height down the panel and
+ * a reader can scan it. A feature with no strand piles with the forward ones.
+ */
+function strandpileLanes(
+  rows: [string, Unlaned[]][],
+): Map<string, RowPanelSpan[]> {
+  const piled = rows.map(([name, bands]) => {
+    const reverse = packDomainLanes(
+      bands.filter(b => b.annotation.strand === -1),
+    )
+    const forward = packDomainLanes(
+      bands.filter(b => b.annotation.strand !== -1),
+    )
+    return { name, forward, reverse }
+  })
+  const up = Math.max(0, ...piled.map(p => p.forward[0]?.laneCount ?? 0))
+  const down = Math.max(0, ...piled.map(p => p.reverse[0]?.laneCount ?? 0))
+  const laneCount = up + down
+  return new Map(
+    piled.map(({ name, forward, reverse }) => [
+      name,
+      [
+        // forward level 0 is the lane just above the line, stacking upward
+        ...forward.map(b => ({ ...b, lane: up - 1 - b.lane, laneCount })),
+        ...reverse.map(b => ({ ...b, lane: up + b.lane, laneCount })),
+      ],
+    ]),
+  )
+}
+
+/** one row's spans laid out by the panel's `position` */
+function panelLanes(
+  panel: RowFeaturesSpec,
+  rows: [string, Unlaned[]][],
+): Map<string, RowPanelSpan[]> {
+  return panel.position === 'strandpile'
+    ? strandpileLanes(rows)
+    : new Map(rows.map(([name, bands]) => [name, packDomainLanes(bands)]))
+}
+
+/**
+ * The spans a `features` panel draws, keyed by row name and measured in the
+ * panel's own pixels. `column` takes the bands the overlay draws, at the
+ * alignment's column width. `position` packs each row's features in its own
+ * residue positions, shifted by an `align` transform, and maps the extent they
+ * cover across every row onto the panel width, so a row with no alignment
+ * still has an x.
+ */
+export function featurePanelSpans({
+  panel,
+  width,
+  colWidth,
+  domainBands,
+  annotationsByRow,
+  shifts,
+}: {
+  panel: RowFeaturesSpec
+  width: number
+  colWidth: number
+  domainBands: Map<string, DomainBand[]>
+  annotationsByRow: Record<string, Annotation[]>
+  shifts: Map<string, number> | undefined
+}): Map<string, RowPanelSpan[]> {
+  if (panel.x === 'column') {
+    return panelLanes(
+      panel,
+      [...domainBands].map(([name, bands]) => [
+        name,
+        bands.map(band => ({
+          ...band,
+          xStart: band.startCol * colWidth,
+          xEnd: band.endCol * colWidth,
+        })),
+      ]),
+    )
+  }
+  const shifted = Object.entries(annotationsByRow).map(
+    ([name, annotations]) => {
+      const shift = shifts?.get(name) ?? 0
+      return [
+        name,
+        annotations.map(annotation => ({
+          annotation,
+          start: annotation.start - 1 + shift,
+          end: annotation.end + shift,
+        })),
+      ] as const
+    },
+  )
+  let min = Infinity
+  let max = -Infinity
+  for (const [, features] of shifted) {
+    for (const { start, end } of features) {
+      min = Math.min(min, start)
+      max = Math.max(max, end)
+    }
+  }
+  // a gene arrow ends where its feature does, so the extent maps onto the whole
+  // panel less the pixel the rightmost stroke needs
+  const drawable = Math.max(1, width - 1)
+  const scale = max > min ? drawable / (max - min) : 0
+  // a lane opens where a span covers more than a tenth of the one before it,
+  // which keeps the genes of an operon on one lane: adjacent genes commonly
+  // share a few bases, and a stop codon overlapping the next start reads as a
+  // second lane over the whole row
+  return panelLanes(
+    panel,
+    shifted.map(([name, features]) => [
+      name,
+      features.map(({ annotation, start, end }) => ({
+        annotation,
+        xStart: (start - min) * scale,
+        xEnd: (end - min) * scale,
+        startCol: start,
+        endCol: end - (end - start) * laneOverlap,
+      })),
+    ]),
+  )
+}
+
+// a scale over the values a field takes across every feature loaded, so hiding
+// a type in the filter dialog leaves the rest in their colors, and a legend of
+// the values the features drawn carry
+export function resolveFeatureScale(
+  field: string,
+  scale: ScaleSpec | undefined,
+  annotations: Annotation[],
+  drawn: Annotation[],
+) {
+  const valuesOf = (list: Annotation[]) =>
+    list.map(a => featureField(a, field)).filter(notEmpty)
+  const resolved = resolveScale(scale, valuesOf(annotations))
+  const shown = new Set(valuesOf(drawn))
+  return {
+    field,
+    ...resolved,
+    legend: resolved.legend.filter(entry => shown.has(entry.id)),
+  }
+}

package/src/filehandleLoader.ts

@@ -0,0 +1,136 @@
+import { openLocation } from '@jbrowse/core/util/io'
+import { addDisposer, isAlive } from '@jbrowse/mobx-state-tree'
+import { autorun, transaction } from 'mobx'
+
+import { fetchTextWithProgress, isAbortError } from './fetchUtils.ts'
+
+import type { FetchStatus } from './fetchUtils.ts'
+import type { FileLocation } from '@jbrowse/core/util/types'
+import type { IStateTreeNode } from '@jbrowse/mobx-state-tree'
+
+interface LoaderHost extends IStateTreeNode {
+  setStatus: (status?: FetchStatus) => void
+  setError: (error?: unknown) => void
+  addWarning: (warning: string) => void
+}
+
+interface FilehandleLoader {
+  /** the layer's name in a failure message */
+  what: string
+  getFilehandle: () => FileLocation | undefined
+  onLoad: (text: string) => void
+  setLoading?: (loading: boolean) => void
+  /** runs after a local file loads, since a blob has no URL to refetch, and on cancel */
+  clearFilehandle?: () => void
+  /** a failure adds a warning instead of an error */
+  optional?: boolean
+}
+
+/**
+ * Latest-wins abort rotation, after `createAbortRotation` in
+ * jbrowse-components. Each `begin()` aborts the previous fetch and returns a
+ * signal with an `isCurrent()` guard; gate every write after an await on it so a
+ * superseded or torn-down fetch cannot overwrite fresher data. `end()` in the
+ * `finally` closes the guard of a fetch that completed.
+ */
+export function createAbortRotation(self: IStateTreeNode) {
+  let current: { controller: AbortController; ended: boolean } | undefined
+  return {
+    /** aborts the running fetch, and returns whether one was running */
+    cancel() {
+      const running = current !== undefined && !current.ended
+      current?.controller.abort()
+      current = undefined
+      return running
+    },
+    begin() {
+      current?.controller.abort()
+      const mine = { controller: new AbortController(), ended: false }
+      current = mine
+      return {
+        controller: mine.controller,
+        isCurrent: () => !mine.ended && mine === current && isAlive(self),
+        end() {
+          mine.ended = true
+        },
+      }
+    },
+  }
+}
+
+/**
+ * Fetches the filehandle whenever it changes and hands the text to `onLoad`. A
+ * superseded or cleared request is aborted and clears its status line.
+ */
+export function installFilehandleLoader(
+  self: LoaderHost,
+  {
+    what,
+    getFilehandle,
+    onLoad,
+    setLoading,
+    clearFilehandle,
+    optional = false,
+  }: FilehandleLoader,
+) {
+  const rotation = createAbortRotation(self)
+  const cancel = () => {
+    if (rotation.cancel() && isAlive(self)) {
+      self.setStatus(undefined)
+    }
+  }
+  addDisposer(self, cancel)
+  addDisposer(
+    self,
+    autorun(async () => {
+      const filehandle = getFilehandle()
+      cancel()
+      if (!filehandle) {
+        setLoading?.(false)
+        return
+      }
+      const { controller, isCurrent, end } = rotation.begin()
+      try {
+        setLoading?.(true)
+        if (!optional) {
+          self.setError(undefined)
+        }
+        const text = await fetchTextWithProgress(
+          openLocation(filehandle),
+          status => {
+            if (isCurrent()) {
+              self.setStatus(status)
+            }
+          },
+          { controller },
+        )
+        if (isCurrent()) {
+          transaction(() => {
+            onLoad(text)
+            if (filehandle.locationType === 'BlobLocation') {
+              clearFilehandle?.()
+            }
+          })
+        }
+      } catch (e) {
+        if (isCurrent()) {
+          if (isAbortError(e)) {
+            clearFilehandle?.()
+          } else {
+            console.error(e)
+            if (optional) {
+              self.addWarning(`The ${what} did not load: ${e}`)
+            } else {
+              self.setError(e)
+            }
+          }
+        }
+      } finally {
+        if (isCurrent()) {
+          setLoading?.(false)
+        }
+        end()
+      }
+    }),
+  )
+}

package/src/headlessRenderEnv.ts

@@ -12,7 +12,9 @@
  * leaves the rest undefined -- every emitted transform then carries `NaN` in its
  * x components, which no assertion on a drawn x-position can survive.
  */
-export class HeadlessDOMMatrix {
+import { CHAR_WIDTH_RATIO } from './measureTextCanvas.ts'
+
+class HeadlessDOMMatrix {
   a: number
   b: number
   c: number
@@ -50,7 +52,7 @@ export class HeadlessDOMMatrix {
   }
 }
 
-export class HeadlessDOMPoint {
+class HeadlessDOMPoint {
   constructor(
     public x = 0,
     public y = 0,
@@ -69,10 +71,11 @@ export class HeadlessDOMPoint {
  * its own jsdom passes that window instead, because Node has no global
  * HTMLCanvasElement to patch.
  *
- * `measureText` reports 0.6em per character, close enough to a real sans-serif
- * average for layout and, more usefully, exactly predictable: a caller can
- * compute the width a renderer will see rather than hardcoding a number
- * measured from one machine's fonts.
+ * Without `measureContext`, `measureText` reports 0.6em per character, close
+ * enough to a real sans-serif average for layout and exactly predictable: a
+ * test can compute the width a renderer will see. A caller with a real canvas,
+ * such as react-msaview-cli with @napi-rs/canvas, passes one of its 2D
+ * contexts as `measureContext` to measure with the installed fonts.
  *
  * `contextExtras` adds to the context a test hands out -- the raster test
  * supplies the ImageData methods that make the export take its image path.
@@ -80,6 +83,7 @@ export class HeadlessDOMPoint {
 export function installHeadlessRenderEnv(
   win: unknown = globalThis,
   contextExtras: Partial<CanvasRenderingContext2D> = {},
+  measureContext?: MeasureContext,
 ) {
   const g = globalThis as Record<string, unknown>
   g.DOMMatrix = HeadlessDOMMatrix
@@ -96,14 +100,23 @@ export function installHeadlessRenderEnv(
         set font(v: string) {
           font = v
         },
-        measureText: (t: string) => ({
-          width: t.length * (Number.parseFloat(font) || 10) * CHAR_WIDTH_RATIO,
-        }),
+        measureText: (t: string) => {
+          if (measureContext) {
+            measureContext.font = font
+            return { width: measureContext.measureText(t).width }
+          }
+          return {
+            width:
+              t.length * (Number.parseFloat(font) || 10) * CHAR_WIDTH_RATIO,
+          }
+        },
       },
       contextExtras,
     ) as unknown as CanvasRenderingContext2D
   } as unknown as typeof HTMLCanvasElement.prototype.getContext
 }
 
-/** the per-character width factor `measureText` above reports */
-export const CHAR_WIDTH_RATIO = 0.6
+export interface MeasureContext {
+  font: string
+  measureText(text: string): { width: number }
+}

package/src/hierarchy.ts

@@ -61,56 +61,6 @@ export function hierarchy<T>(
   return coreHierarchy(data, childrenAccessor)
 }
 
-export function clusterLayout<T>(
-  root: HierarchyNode<T>,
-  sizeX: number,
-  sizeY: number,
-) {
-  const leafNodes = leaves(root)
-  const n = leafNodes.length
-  const step = sizeX / n
-
-  for (let i = 0; i < n; i++) {
-    leafNodes[i]!.x = (i + 0.5) * step
-  }
-
-  // x of an internal node is the mean of its children's x, so process in
-  // post-order (children before parents). The subtree span comes from the same
-  // pass, for the block culls in the tree renderer.
-  const nodes = descendants(root)
-  for (let i = nodes.length - 1; i >= 0; i--) {
-    const node = nodes[i]!
-    if (node.children) {
-      let sum = 0
-      let min = Infinity
-      let max = -Infinity
-      for (const child of node.children) {
-        sum += child.x!
-        min = Math.min(min, child.xMin!)
-        max = Math.max(max, child.xMax!)
-      }
-      node.x = sum / node.children.length
-      node.xMin = min
-      node.xMax = max
-    } else {
-      node.xMin = node.x
-      node.xMax = node.x
-    }
-  }
-
-  const rootHeight = root.height
-  const stack = [{ node: root, depth: 0 }]
-  while (stack.length > 0) {
-    const { node, depth } = stack.pop()!
-    node.y = rootHeight === 0 ? sizeY : (depth / rootHeight) * sizeY
-    if (node.children) {
-      for (const child of node.children) {
-        stack.push({ node: child, depth: depth + 1 })
-      }
-    }
-  }
-}
-
 export interface TreeScale {
   readonly rowHeight: number
   readonly treeWidth: number
@@ -186,10 +136,10 @@ export class LaidOutNode<T> implements HierarchyNode<T> {
 }
 
 /**
- * The layout `clusterLayout` and `setBrLength` write, on new nodes: tips one
- * row apart, a parent at the mean of its children, and branch length measured
- * from the root, whose own branch is not drawn. A collapsed node records the
- * farthest tip of its hidden subtree, where the base of its triangle goes.
+ * The tree laid out on new nodes: tips one row apart, a parent at the mean of
+ * its children, and branch length measured from the root, whose own branch is
+ * not drawn. A collapsed node records the farthest tip of its hidden subtree,
+ * where the base of its triangle goes.
  */
 export function layoutTree<T extends { length?: number }>(
   root: HierarchyNode<T>,
@@ -329,39 +279,6 @@ export function calcDepthToLeaf<T>(node: HierarchyNode<T>): number {
   return node.depthToLeaf!
 }
 
-// Max root-to-leaf sum of branch lengths within the subtree at d. Negative
-// lengths are floored at zero, the same as setBrLength does when it lays the
-// tree out, so the extent this reports is the one that gets drawn
-export function maxLength(d: HierarchyNode): number {
-  const nodes = descendants(d)
-  const pathLen = new Map<HierarchyNode, number>()
-  for (let i = nodes.length - 1; i >= 0; i--) {
-    const n = nodes[i]!
-    let childMax = 0
-    if (n.children) {
-      for (const child of n.children) {
-        childMax = Math.max(childMax, pathLen.get(child)!)
-      }
-    }
-    pathLen.set(n, Math.max(n.data.length || 0, 0) + childMax)
-  }
-  return pathLen.get(d)!
-}
-
-export function setBrLength(d: HierarchyNode, y0: number, k: number) {
-  const stack = [{ node: d, y0 }]
-  while (stack.length > 0) {
-    const { node, y0: acc } = stack.pop()!
-    const next = acc + Math.max(node.data.length || 0, 0)
-    node.len = next * k
-    if (node.children) {
-      for (const child of node.children) {
-        stack.push({ node: child, y0: next })
-      }
-    }
-  }
-}
-
 /**
  * Every leaf by name, with a name two leaves share mapping to undefined: a tip
  * set naming it cannot say which tip it means.
@@ -416,7 +333,7 @@ export function mrca<T extends { name: string }>(
 
 /**
  * The deepest node whose subtree covers a run of rows, given in the row-space
- * coordinates clusterLayout writes to xMin/xMax. A subtree's leaves are one
+ * coordinates layoutTree writes to xMin/xMax. A subtree's leaves are one
  * contiguous run, so at most one child per level covers the run and the descent
  * visits the tree's depth rather than its nodes.
  */

package/src/index.ts

@@ -11,10 +11,8 @@ export { renderToSvg } from './renderToSvg.tsx'
 export type { ExportSvgOptions } from './renderToSvg.tsx'
 // renderToSvg outside a browser needs DOM bits jsdom omits; react-msaview-cli
 // and the README figure generator both drive it that way
-export {
-  CHAR_WIDTH_RATIO,
-  installHeadlessRenderEnv,
-} from './headlessRenderEnv.ts'
+export { installHeadlessRenderEnv } from './headlessRenderEnv.ts'
+export { CHAR_WIDTH_RATIO } from './measureTextCanvas.ts'
 // the row count above which calculateNeighborJoiningTreeFromMSA throws, for
 // hosts gating their own menu item
 export { maxNeighborJoiningRows } from './constants.ts'
@@ -27,8 +25,13 @@ export type {
   RegionShorthand,
 } from './expandSpec.ts'
 export { default as MSAView } from './components/Loading.tsx'
+export type { ToolbarSlots } from './components/header/Header.tsx'
 export { default as MSAViewer } from './components/MSAViewer.tsx'
 export type { MSAViewerProps } from './components/MSAViewer.tsx'
+// the snapshot MSAViewer builds from its props, for the CLI's --props
+export { resolveTheme, viewerSnapshot } from './viewerSnapshot.ts'
+// the active scheme's hex color for a row residue, to paint a structure with
+export { schemeResidueColor } from './schemeResidueColor.ts'
 export { mount } from './mount.tsx'
 export { defineMsaElement } from './element.ts'
 export { useMsaSvgFigure } from './useMsaSvgFigure.ts'
@@ -37,7 +40,7 @@ export type { MountedViewer } from './mount.tsx'
 export { type MsaViewModel, default as MSAModelF } from './model.ts'
 export type { MSAFormat, MSAParserType } from 'msa-parsers'
 export type { HierarchyNode, LaidOutNode, TreeScale } from './hierarchy.ts'
-// InterProScanResults is the EBI wire format that setDomains still accepts;
+// InterProScanResults is the EBI wire format interProScanToAnnotations reads;
 // Annotation is the source-agnostic shape everything else is written against
 export type { InterProScanResults } from 'msa-parsers'
 // ColumnCounts, ColumnStats, DomainBand and TidyDomainAnnotation surface in the
@@ -47,6 +50,7 @@ export type { InterProScanResults } from 'msa-parsers'
 // reason.
 export type { ColumnCounts } from './columnCounts.ts'
 export type { ColumnStats } from './columnStats.ts'
+export type { ZoomSnapshot } from './zoomSnapshot.ts'
 // the scale an encoding reads its field through, and what resolving one gives
 export type { ResolvedScale, ScaleSpec } from './scales.ts'
 export type {

package/src/measureTextCanvas.ts

@@ -16,16 +16,18 @@ function getCtx() {
   return ctxHandle
 }
 
-// Rough average glyph width as a fraction of the font size for the sans-serif
-// stack the tree labels use. Only reached where there is no canvas to measure
-// with (jsdom, SSR); estimating the label gutter beats throwing out of the
-// layout getters that read this on every render.
-const fallbackGlyphWidthRatio = 0.6
+/**
+ * Rough average glyph width as a fraction of the font size for the sans-serif
+ * stack the labels use. measureTextCanvas falls back on it where there is no
+ * canvas to measure with (jsdom, SSR), and the headless render environment's
+ * `measureText` reports it.
+ */
+export const CHAR_WIDTH_RATIO = 0.6
 
 export function measureTextCanvas(text: string, fontSize: number) {
   const ctx = getCtx()
   if (!ctx) {
-    return text.length * fontSize * fallbackGlyphWidthRatio
+    return text.length * fontSize * CHAR_WIDTH_RATIO
   }
   setFontSize(ctx, fontSize)
   return ctx.measureText(text).width