react-msaview 6.5.0 → 8.0.0

package/src/featureFields.ts

@@ -0,0 +1,19 @@
+import type { Annotation } from './types.ts'
+
+/**
+ * The value a feature gives an encoded field: an Annotation property, else one
+ * of the GFF attributes the parser kept.
+ */
+export function featureField(annotation: Annotation, field: string) {
+  const own = (annotation as unknown as Record<string, unknown>)[field]
+  const value = own ?? annotation.attributes?.[field]
+  return typeof value === 'string' ? value : undefined
+}
+
+/**
+ * The name a feature answers to in a transform: its GFF `Name` attribute, else
+ * the name the parser gave it.
+ */
+export function featureName(annotation: Annotation) {
+  return featureField(annotation, 'Name') ?? featureField(annotation, 'name')
+}

package/src/fetchUtils.ts

@@ -19,7 +19,6 @@ function statusMessageText(status: RpcStatus | undefined) {
 
 export interface FetchStatus {
   msg: string
-  url?: string
   onCancel?: () => void
 }
 
@@ -34,14 +33,18 @@ type ProgressFetcher = (
  * Fetch text from a filehandle while reporting download/unzip progress through
  * setStatus, and wiring a Cancel handler that aborts the underlying request.
  * The status is always cleared once the fetch settles. The fetcher is injectable
- * for testing.
+ * for testing, and so is the AbortController: a caller that can supersede its
+ * own request -- the model's loaders, when the filehandle changes under them --
+ * holds one and aborts the download it no longer wants.
  */
 export async function fetchTextWithProgress(
   loc: Filehandle,
   setStatus: (status?: FetchStatus) => void,
-  fetcher: ProgressFetcher = fetchAndMaybeUnzipText,
+  {
+    fetcher = fetchAndMaybeUnzipText,
+    controller = new AbortController(),
+  }: { fetcher?: ProgressFetcher; controller?: AbortController } = {},
 ) {
-  const controller = new AbortController()
   try {
     return await fetcher(loc, {
       signal: controller.signal,
@@ -64,42 +67,6 @@ export async function fetchTextWithProgress(
   }
 }
 
-export async function myfetch(url: string, args?: RequestInit) {
-  const response = await fetch(url, args)
-
-  if (!response.ok) {
-    throw new Error(
-      `HTTP ${response.status} fetching ${url} ${await response.text()}`,
-    )
-  }
-
-  return response
-}
-
-export async function textfetch(url: string, args?: RequestInit) {
-  const response = await myfetch(url, args)
-  return response.text()
-}
-
-export async function jsonfetch<T>(url: string, args?: RequestInit) {
-  const response = await myfetch(url, args)
-  return response.json() as T
-}
-
-export function timeout(time: number, signal?: AbortSignal) {
-  return new Promise<void>((resolve, reject) => {
-    if (signal?.aborted) {
-      reject(new DOMException('Aborted', 'AbortError'))
-    } else {
-      const id = setTimeout(resolve, time)
-      signal?.addEventListener('abort', () => {
-        clearTimeout(id)
-        reject(new DOMException('Aborted', 'AbortError'))
-      })
-    }
-  })
-}
-
 export function isAbortError(e: unknown) {
   return e instanceof DOMException && e.name === 'AbortError'
 }

package/src/flatToTree.ts

@@ -22,8 +22,7 @@ export function flatToTree(items: FlatItem[]): TreeNode {
         item.id,
         {
           id: `${item.id}`,
-          // the label is what NCBI's own tree viewer shows; falling back to the
-          // node id would render a tree of bare numbers
+          // NCBI's tree viewer shows the label
           name: item.label || `${item.id}`,
           ...(length !== undefined && Number.isFinite(length)
             ? { length }

package/src/ggplotPalettes.ts

@@ -19,3 +19,63 @@ const palettes = [
 ]
 
 export default palettes
+
+/**
+ * Fixed categorical palettes a scale names. `ggplot` is not one of them: it is
+ * the ramp above, which picks its colors from the number of keys.
+ */
+export const namedPalettes: Record<string, readonly string[]> = {
+  set1: [
+    '#e41a1c',
+    '#377eb8',
+    '#4daf4a',
+    '#984ea3',
+    '#ff7f00',
+    '#ffff33',
+    '#a65628',
+    '#f781bf',
+    '#999999',
+  ],
+  dark2: [
+    '#1b9e77',
+    '#d95f02',
+    '#7570b3',
+    '#e7298a',
+    '#66a61e',
+    '#e6ab02',
+    '#a6761d',
+    '#666666',
+  ],
+  // Okabe-Ito, which stays distinguishable under the common forms of color
+  // blindness
+  okabeito: [
+    '#e69f00',
+    '#56b4e9',
+    '#009e73',
+    '#f0e442',
+    '#0072b2',
+    '#d55e00',
+    '#cc79a7',
+    '#000000',
+  ],
+  tableau: [
+    '#4e79a7',
+    '#f28e2b',
+    '#e15759',
+    '#76b7b2',
+    '#59a14f',
+    '#edc948',
+    '#b07aa1',
+    '#ff9da7',
+    '#9c755f',
+    '#bab0ac',
+  ],
+}
+
+/**
+ * The colors a palette name asks for. `ggplot`, an unknown name, and no name at
+ * all give undefined, which `createPaletteMap` answers with the hue ramp.
+ */
+export function paletteNamed(name?: string) {
+  return name === undefined ? undefined : namedPalettes[name]
+}

package/src/hierarchy.ts

@@ -25,6 +25,11 @@ export interface HierarchyNode<T = NodeWithIds> extends CoreHierarchyNode<T> {
   parent: HierarchyNode<T> | null
   x?: number
   y?: number
+  // the span of `x` over this node's subtree, set by clusterLayout. Leaves are
+  // laid out in order, so a subtree occupies one contiguous run of rows and a
+  // renderer can skip the whole thing when the run misses its block.
+  xMin?: number
+  xMax?: number
   len?: number
   depthToLeaf?: number
   _children?: HierarchyNode<T>[] | null
@@ -33,10 +38,8 @@ export interface HierarchyNode<T = NodeWithIds> extends CoreHierarchyNode<T> {
   collapsedTipXFar?: number
 }
 
-// The generic traversals live in @gmod/newick now, shared with the tree sidebar
-// in jbrowse-components. They are iterative there for the reason they were here:
-// a phylogenetic tree can be a caterpillar, whose depth equals its leaf count,
-// and the recursive form overflows the stack somewhere past 5000 tips.
+// The @gmod/newick traversals are iterative: a caterpillar tree's depth equals
+// its leaf count, and recursion overflows the stack past about 5000 tips.
 export {
   descendants,
   find,
@@ -49,11 +52,8 @@ export {
 }
 export type { HierarchyLink } from '@gmod/newick'
 
-// coreHierarchy builds base nodes, and the layout fields above are written onto
-// them afterwards by this package. Every one of those fields is optional, so the
-// two node types are mutually assignable and this needs no cast -- it exists
-// only to declare the wider return type, which is what lets those later
-// assignments typecheck.
+// declares the wider return type so the layout code can assign the optional
+// fields above onto coreHierarchy's nodes
 export function hierarchy<T>(
   data: T,
   childrenAccessor: (d: T) => T[] | undefined,
@@ -75,16 +75,26 @@ export function clusterLayout<T>(
   }
 
   // x of an internal node is the mean of its children's x, so process in
-  // post-order (children before parents)
+  // 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
     }
   }
 
@@ -172,15 +182,9 @@ export function calcDepthToLeaf<T>(node: HierarchyNode<T>): number {
   return node.depthToLeaf!
 }
 
-export function findMaxBranchLen(node: HierarchyNode): number {
-  let maxLen = 0
-  for (const n of descendants(node)) {
-    maxLen = Math.max(maxLen, n.len || 0)
-  }
-  return maxLen
-}
-
-// Max root-to-leaf sum of branch lengths within the subtree at d
+// 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>()
@@ -192,7 +196,7 @@ export function maxLength(d: HierarchyNode): number {
         childMax = Math.max(childMax, pathLen.get(child)!)
       }
     }
-    pathLen.set(n, (n.data.length || 0) + childMax)
+    pathLen.set(n, Math.max(n.data.length || 0, 0) + childMax)
   }
   return pathLen.get(d)!
 }
@@ -210,3 +214,76 @@ export function setBrLength(d: HierarchyNode, y0: number, k: number) {
     }
   }
 }
+
+/**
+ * Every leaf by name, with a name two leaves share mapping to undefined: a tip
+ * set naming it cannot say which tip it means.
+ */
+export function leafIndex<T extends { name: string }>(root: HierarchyNode<T>) {
+  const index = new Map<string, HierarchyNode<T> | undefined>()
+  for (const leaf of leaves(root)) {
+    const { name } = leaf.data
+    index.set(name, index.has(name) ? undefined : leaf)
+  }
+  return index
+}
+
+/**
+ * The most recent common ancestor of a set of tip names, or undefined when a
+ * name is not a tip of this tree or names two of them.
+ *
+ * Each name lifts through `parent` to the ancestor the names before it share,
+ * so the walk holds two nodes. Recording a root-to-tip path per name instead
+ * costs the depth in memory per name, and a caterpillar tree's depth is its tip
+ * count. `index` is `leafIndex(root)`, which a caller resolving several tip
+ * sets against one tree builds once.
+ */
+export function mrca<T extends { name: string }>(
+  root: HierarchyNode<T>,
+  names: string[],
+  index = leafIndex(root),
+) {
+  let node: HierarchyNode<T> | undefined
+  for (const name of names) {
+    let other = index.get(name)
+    if (!other) {
+      return undefined
+    }
+    if (!node) {
+      node = other
+      continue
+    }
+    while (node.depth > other.depth) {
+      node = node.parent!
+    }
+    while (other.depth > node.depth) {
+      other = other.parent!
+    }
+    while (node !== other) {
+      node = node.parent!
+      other = other.parent!
+    }
+  }
+  return node
+}
+
+/**
+ * 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
+ * contiguous run, so at most one child per level covers the run and the descent
+ * visits the tree's depth rather than its nodes.
+ */
+export function nodeCoveringRows<T>(
+  root: HierarchyNode<T>,
+  top: number,
+  bottom: number,
+) {
+  let node = root
+  for (;;) {
+    const child = node.children?.find(c => c.xMin! <= top && c.xMax! >= bottom)
+    if (!child) {
+      return node
+    }
+    node = child
+  }
+}

package/src/index.ts

@@ -1,10 +1,12 @@
 // PUBLIC API — consumed by external JBrowse 2 plugins. Changing or removing any
 // export here is a breaking change for downstream repos:
-//   - jbrowse-plugin-msaview   (wraps MSAModelF + MSAView into a JBrowse view)
-//   - jbrowse-plugin-protein3d (drives MSA<->structure hover/highlight sync)
+//   - jbrowse-plugin-msaview (wraps MSAModelF + MSAView into a JBrowse view)
+//   - jbrowse-plugin-tview   (the same, for a tree-first view)
 // Those plugins also reach into the MsaViewModel instance at runtime; the model
 // members they rely on (e.g. mouseCol/setMousePos, setHighlightedColumns,
 // seqPosToVisibleCol/visibleColToSeqPos) are flagged inline in model.ts.
+// jbrowse-plugin-protein3d no longer depends on this package at all: it reads
+// the msaview plugin's model through a structural type of its own.
 export { renderToSvg } from './renderToSvg.tsx'
 export type { ExportSvgOptions } from './renderToSvg.tsx'
 // renderToSvg outside a browser needs DOM bits jsdom omits; react-msaview-cli
@@ -13,31 +15,69 @@ export {
   CHAR_WIDTH_RATIO,
   installHeadlessRenderEnv,
 } from './headlessRenderEnv.ts'
+// the row count above which calculateNeighborJoiningTreeFromMSA throws, for
+// hosts gating their own menu item
+export { maxNeighborJoiningRows } from './constants.ts'
 export { default as MSAView } from './components/Loading.tsx'
 export { default as MSAViewer } from './components/MSAViewer.tsx'
+export type { MSAViewerProps } from './components/MSAViewer.tsx'
+export { mount } from './mount.tsx'
+export { defineMsaElement } from './element.ts'
+export { useMsaSvgFigure } from './useMsaSvgFigure.ts'
+export type { MsaSvgFigure } from './useMsaSvgFigure.ts'
+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 } from './hierarchy.ts'
 // InterProScanResults is the EBI wire format that setDomains still accepts;
 // Annotation is the source-agnostic shape everything else is written against
 export type { InterProScanResults } from 'msa-parsers'
-// ColumnCounts, DomainBand and TidyDomainAnnotation surface in the inferred type
-// of the composed state model, so a downstream plugin cannot emit declarations
-// for its own stateModelFactory without being able to name them (TS2883).
-// jbrowse-plugin-msaview already re-exports MSAFormat for exactly this reason.
+// ColumnCounts, ColumnStats, DomainBand and TidyDomainAnnotation surface in the
+// inferred type of the composed state model, so a downstream plugin cannot emit
+// declarations for its own stateModelFactory without being able to name them
+// (TS2883). jbrowse-plugin-msaview already re-exports MSAFormat for exactly this
+// reason.
 export type { ColumnCounts } from './columnCounts.ts'
+export type { ColumnStats } from './columnStats.ts'
+// the scale an encoding reads its field through, and what resolving one gives
+export type { ResolvedScale, ScaleSpec } from './scales.ts'
 export type {
   Accession,
   Annotation,
+  Arc,
+  ArcSpec,
+  ArcTrackModel,
   BasicTrack,
   BasicTrackModel,
+  Cell,
+  Clade,
+  CladeMark,
   ColumnTrackSpec,
   DomainBand,
+  Encoding,
+  EncodingChannel,
   Highlight,
+  Legend,
+  LegendEntry,
   Node,
+  MappedStructure,
   NodeWithIds,
   NodeWithIdsAndLength,
+  Region,
+  ResidueEncoding,
+  ResidueMapping,
+  ResidueMappingProblem,
+  ResidueSegment,
+  ResolvedClade,
+  ResolvedEncoding,
   ResolvedHighlight,
+  ResolvedRowPanel,
+  RowPanelSpec,
+  RowResidue,
+  StructureResidue,
   TextTrackModel,
   TidyDomainAnnotation,
+  TrackKind,
+  UnshareableData,
+  Viewport,
 } from './types.ts'

package/src/model/DataModel.ts

@@ -1,5 +1,7 @@
 import { types } from '@jbrowse/mobx-state-tree'
 
+import { maxInlineSnapshotBytes } from '../constants.ts'
+
 /**
  * #stateModel DataModel
  * the data stored for the model. this is sometimes temporary in the case that
@@ -54,13 +56,12 @@ export function DataModelF() {
       },
     }))
     .postProcessSnapshot(snap =>
-      // a large document is dropped from the snapshot rather than inlined
-      // into a session or a shared URL, and every field here holds one, so
-      // the rule is the same for all of them
+      // drops any field over maxInlineSnapshotBytes; the parent model's
+      // `unshareableData` reports what was dropped
       Object.fromEntries(
         Object.entries(snap).map(([key, text]) => [
           key,
-          text && text.length > 50_000 ? undefined : text,
+          text && text.length > maxInlineSnapshotBytes ? undefined : text,
         ]),
       ),
     )

package/src/model/msaModel.ts

@@ -31,8 +31,9 @@ export function MSAModelF() {
 
       /**
        * #property
-       * show a per-column statistics tooltip (consensus, conservation, gaps,
-       * residue distribution) while hovering the alignment
+       * show a tooltip with the hovered column's value for a track while
+       * hovering that track: the conservation scores, the logo's composition,
+       * an arc's partner columns
        */
       showColumnStats: stripDefault(types.boolean, defaultShowColumnStats),
 

package/src/model/treeModel.ts

@@ -3,9 +3,12 @@ import { types } from '@jbrowse/mobx-state-tree'
 import {
   defaultDrawLabels,
   defaultDrawNodeBubbles,
+  defaultDrawNodeLabels,
   defaultDrawTree,
   defaultLabelsAlignRight,
+  defaultOverviewHeight,
   defaultShowBranchLen,
+  defaultShowTreeOverview,
   defaultTreeAreaWidth,
   defaultTreeWidth,
 } from '../constants.ts'
@@ -60,6 +63,26 @@ export function TreeModelF() {
        */
       drawNodeBubbles: stripDefault(types.boolean, defaultDrawNodeBubbles),
 
+      /**
+       * #property
+       * draw the label a newick file gives an internal node, which is where a
+       * bootstrap or posterior support value lands
+       */
+      drawNodeLabels: stripDefault(types.boolean, defaultDrawNodeLabels),
+
+      /**
+       * #property
+       * draw the whole tree small above the tree panel, with the focused
+       * subtree boxed. A click on it focuses the subtree under the pointer
+       */
+      showTreeOverview: stripDefault(types.boolean, defaultShowTreeOverview),
+
+      /**
+       * #property
+       * height of the tree overview band, px
+       */
+      overviewHeight: stripDefault(types.number, defaultOverviewHeight),
+
       /**
        * #property
        * auto-size treeAreaWidth to fit the row labels (plus the tree, if drawn)
@@ -116,6 +139,25 @@ export function TreeModelF() {
       setDrawNodeBubbles(arg: boolean) {
         self.drawNodeBubbles = arg
       },
+      /**
+       * #action
+       */
+      setDrawNodeLabels(arg: boolean) {
+        self.drawNodeLabels = arg
+      },
+      /**
+       * #action
+       */
+      setShowTreeOverview(arg: boolean) {
+        self.showTreeOverview = arg
+      },
+      /**
+       * #action
+       * set the height of the tree overview band (px)
+       */
+      setOverviewHeight(n: number) {
+        self.overviewHeight = Math.round(n)
+      },
       /**
        * #action
        */