react-msaview 8.2.0 → 8.4.0

package/src/components/tree/useTreeHover.ts

@@ -1,21 +1,16 @@
 import { useState } from 'react'
 
+import { useHoverAnchor } from '../useHoverAnchor.ts'
 import { ClickMapIndex } from './clickMap.ts'
 
 import type { MsaViewModel } from '../../model.ts'
 import type { ClickEntry } from './clickMap.ts'
 import type React from 'react'
 
-export interface TreeHoverTarget extends ClickEntry {
-  clientX: number
-  clientY: number
-}
-
 /**
  * Owns hit-testing for one tree block: the spatial index the render pass fills
- * in, the entry currently under the pointer, and the model hover state that the
- * MSA panel mirrors. The index is a render artifact rather than display state, so
- * it lives in a ref; everything the component draws comes back as plain state.
+ * in, the entry under the pointer with its tooltip anchor, and the model hover
+ * state that the MSA panel mirrors.
  */
 export function useTreeHover({
   model,
@@ -25,10 +20,10 @@ export function useTreeHover({
   offsetY: number
 }) {
   const [clickMap] = useState(() => new ClickMapIndex())
-  const [hovered, setHovered] = useState<TreeHoverTarget>()
+  const { anchor, hoverAt, clearAnchor } = useHoverAnchor<ClickEntry>()
 
   // leaf labels win over the branch/bubble targets they overlap, so a click on a
-  // name opens the node menu rather than the branch menu
+  // name opens the leaf's menu
   function hitTest(event: React.MouseEvent) {
     const x = event.nativeEvent.offsetX
     const y = event.nativeEvent.offsetY + offsetY
@@ -43,11 +38,7 @@ export function useTreeHover({
 
   function onMouseMove(event: React.MouseEvent) {
     const entry = hitTest(event)
-    setHovered(
-      entry
-        ? { ...entry, clientX: event.clientX, clientY: event.clientY }
-        : undefined,
-    )
+    hoverAt(event, entry)
     // hovering an internal node highlights every tip below it; hovering a leaf
     // label additionally drives the single-row highlight
     model.setHoveredTreeNode(entry?.id)
@@ -58,10 +49,10 @@ export function useTreeHover({
   }
 
   function onMouseLeave() {
-    setHovered(undefined)
+    clearAnchor()
     model.setHoveredTreeNode(undefined)
     model.setMousePos(undefined, undefined)
   }
 
-  return { clickMap, hovered, hitTest, onMouseMove, onMouseLeave }
+  return { clickMap, anchor, hitTest, onMouseMove, onMouseLeave }
 }

package/src/components/useHoverAnchor.ts

@@ -0,0 +1,31 @@
+import { useState } from 'react'
+
+export interface HoverAnchor<T> {
+  clientPoint: { x: number; y: number }
+  value: T
+}
+
+/**
+ * The thing under the pointer and the point a tooltip about it hangs from,
+ * 15px below the cursor so the tooltip clears it.
+ */
+export function useHoverAnchor<T>() {
+  const [anchor, setAnchor] = useState<HoverAnchor<T>>()
+
+  function hoverAt(
+    event: { clientX: number; clientY: number },
+    value: T | undefined,
+  ) {
+    setAnchor(
+      value === undefined
+        ? undefined
+        : { value, clientPoint: { x: event.clientX, y: event.clientY + 15 } },
+    )
+  }
+
+  function clearAnchor() {
+    setAnchor(undefined)
+  }
+
+  return { anchor, hoverAt, clearAnchor }
+}

package/src/constants.ts

@@ -1,3 +1,5 @@
+import type { TreeOrder } from './types.ts'
+
 // Main model defaults
 export const defaultRowHeight = 16
 export const defaultColWidth = 12
@@ -75,6 +77,13 @@ export const defaultLabelsAlignRight = false
 export const defaultTreeAreaWidth = 400
 export const defaultTreeWidth = 300
 export const defaultShowBranchLen = true
+export const treeOrders = [
+  'branchLength',
+  'input',
+  'ladderize',
+  'ladderizeReverse',
+] as const satisfies readonly TreeOrder[]
+export const defaultTreeOrder: TreeOrder = 'branchLength'
 export const defaultDrawTree = true
 export const defaultDrawNodeBubbles = true
 export const defaultDrawNodeLabels = false
@@ -97,9 +106,11 @@ export const rowTintAlpha = 0.25
 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.
+// The largest inline document a snapshot carries by default, which keeps a
+// jbrowse session small. A larger pasted or locally-opened file stays in the
+// live model and out of the snapshot, and `unshareableData` warns using the
+// same number. `MSAModelF({ maxInlineSnapshotBytes })` sets another; the demo
+// app's links hold far more.
 export const maxInlineSnapshotBytes = 50_000
 
 // Height of the band the `rowPanels` headers draw in, above the strips in the

package/src/element.ts

@@ -7,15 +7,26 @@ import type { MsaViewModel } from './model.ts'
 import type { MountedViewer } from './mount.tsx'
 import type {
   Cell,
+  ColorScheme,
   ColumnTrackSpec,
+  Feature,
   Highlight,
+  MsaSelection,
   ResidueMapping,
   Viewport,
 } from './types.ts'
 
 type ElementData = Pick<
   MSAViewerProps,
-  'msa' | 'tree' | 'gff' | 'highlights' | 'columnTracks' | 'residueMappings'
+  | 'msa'
+  | 'tree'
+  | 'gff'
+  | 'features'
+  | 'colorScheme'
+  | 'highlights'
+  | 'columnTracks'
+  | 'residueMappings'
+  | 'selection'
 >
 
 interface NightingaleManager extends HTMLElement {
@@ -78,9 +89,13 @@ function residueRange(model: MsaViewModel, row: string, viewport: Viewport) {
 /**
  * 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.
+ * theme, tree-area-width and reference-row. Properties: msa, tree and gff text,
+ * features, colorScheme, highlights, columnTracks, residueMappings and
+ * selection. The
+ * colorScheme property takes a `{map}` the color-scheme attribute cannot hold,
+ * and wins over the attribute while set. Events: cell-hover, cell-click,
+ * viewport-change and selection-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
@@ -122,6 +137,18 @@ export function defineMsaElement(tagName = 'jbrowse-msa') {
     set gff(value: string | undefined) {
       this.#setData({ gff: value })
     }
+    get features() {
+      return this.#data.features
+    }
+    set features(value: Feature[] | undefined) {
+      this.#setData({ features: value })
+    }
+    get colorScheme() {
+      return this.#data.colorScheme
+    }
+    set colorScheme(value: ColorScheme | undefined) {
+      this.#setData({ colorScheme: value })
+    }
     get highlights() {
       return this.#data.highlights
     }
@@ -140,6 +167,13 @@ export function defineMsaElement(tagName = 'jbrowse-msa') {
     set residueMappings(value: ResidueMapping[] | undefined) {
       this.#setData({ residueMappings: value })
     }
+    // the viewer's selection, which the reader's drags change
+    get selection() {
+      return this.#model ? this.#model.selection : this.#data.selection
+    }
+    set selection(value: MsaSelection | undefined) {
+      this.#setData({ selection: value })
+    }
 
     get #referenceRow() {
       return this.getAttribute('reference-row') ?? undefined
@@ -157,7 +191,10 @@ export function defineMsaElement(tagName = 'jbrowse-msa') {
         msaFilehandle: location(this.getAttribute('msa-url')),
         treeFilehandle: location(this.getAttribute('tree-url')),
         gffFilehandle: location(this.getAttribute('gff-url')),
-        colorScheme: this.getAttribute('color-scheme') ?? undefined,
+        colorScheme:
+          this.#data.colorScheme ??
+          this.getAttribute('color-scheme') ??
+          undefined,
         height: numberAttribute(this.getAttribute('height')),
         treeAreaWidth: numberAttribute(this.getAttribute('tree-area-width')),
         hideHeader: this.hasAttribute('hide-header'),
@@ -173,6 +210,9 @@ export function defineMsaElement(tagName = 'jbrowse-msa') {
           this.#emit('viewport-change', viewport)
           this.#reportRange(viewport)
         },
+        onSelectionChange: selection => {
+          this.#emit('selection-change', selection)
+        },
         onModel: model => {
           this.#model = model
           this.#followRange()

package/src/expandSpec.ts

@@ -59,9 +59,9 @@ function parseSpan(text: string, what: string) {
       `${what} "${text}" is not "start", "start-end" or either followed by a label`,
     )
   }
-  const start = Number(match[1])
-  const end = match[2] === undefined ? start : Number(match[2])
-  return { start, end, label: match[3] }
+  const a = Number(match[1])
+  const b = match[2] === undefined ? a : Number(match[2])
+  return { start: Math.min(a, b), end: Math.max(a, b), label: match[3] }
 }
 
 function withRow<T extends RowChoice>(entry: T, query?: string) {

package/src/exportFileName.ts

@@ -1,12 +1,13 @@
 import type { FileLocation } from '@jbrowse/core/util/types'
 
 /**
- * The name to save an export under: the loaded alignment's file name with the
- * extension swapped, or a plain default when the alignment was pasted in.
+ * The name to save an export under: the loaded file's name with the extension
+ * swapped, or `fallback` when the data was pasted in.
  */
 export function exportFileName(
   location: FileLocation | undefined,
   extension: string,
+  fallback = 'image',
 ) {
   const loc = location as
     | { uri?: string; localPath?: string; name?: string }
@@ -17,5 +18,5 @@ export function exportFileName(
     ?.split(/[/\\]/)
     .pop()
     ?.replace(/\.[^.]*$/, '')
-  return `${base || 'image'}.${extension}`
+  return `${base || fallback}.${extension}`
 }

package/src/featuresLayer.ts

@@ -0,0 +1,48 @@
+import type { Annotation, Feature } from './types.ts'
+
+const placement = new Set(['row', 'start', 'end'])
+
+// The colors and labels are maps keyed by annotation, and a getter read
+// outside a reaction recomputes on every read. Caching on the frozen feature
+// gives it one annotation however often the layer converts.
+const converted = new WeakMap<Feature, Annotation>()
+
+/**
+ * The `features` layer as the annotations a GFF would parse to. Every field
+ * but the placement is also an attribute, as a string like a GFF value, so an
+ * encoding reads `type` or a host's own field the way it reads a GFF column 9
+ * key.
+ */
+export function featuresToAnnotations(features: Feature[]): Annotation[] {
+  return features.map(feature => {
+    const cached = converted.get(feature)
+    if (cached) {
+      return cached
+    }
+    const annotation = featureAnnotation(feature)
+    converted.set(feature, annotation)
+    return annotation
+  })
+}
+
+function featureAnnotation(feature: Feature): Annotation {
+  const { row, start, end, name, description, type, strand, color } = feature
+  const accession = name ?? `${row}:${start}-${end}`
+  const attributes = Object.fromEntries(
+    Object.entries(feature)
+      .filter(([key, value]) => !placement.has(key) && value !== undefined)
+      .map(([key, value]) => [key, String(value)]),
+  )
+  return {
+    id: row,
+    accession,
+    name: name ?? accession,
+    description: description ?? name ?? accession,
+    featureType: type,
+    start,
+    end,
+    strand: strand === '+' ? 1 : strand === '-' ? -1 : undefined,
+    color,
+    attributes,
+  }
+}

package/src/hierarchy.ts

@@ -25,16 +25,16 @@ 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.
+  // the span of `x` over this node's subtree. 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
   // pixel x-position of the farthest tip of a collapsed subtree, where the base
-  // of the collapsed-clade triangle goes. Set in the model's hierarchy getter.
+  // of the collapsed-clade triangle goes
   collapsedTipXFar?: number
 }
 
@@ -111,6 +111,153 @@ export function clusterLayout<T>(
   }
 }
 
+export interface TreeScale {
+  readonly rowHeight: number
+  readonly treeWidth: number
+}
+
+interface LayoutFrame {
+  scale: TreeScale
+  rootToTipLength: number
+}
+
+/**
+ * A node of `layoutTree`: its source node's fields plus its place in unit
+ * space, rows down and branch length across. The pixel getters multiply by the
+ * scale on every read, so a zoom leaves the nodes valid, and an observer
+ * reading `x` observes whatever the scale reads.
+ */
+export class LaidOutNode<T> implements HierarchyNode<T> {
+  data: T
+  depth: number
+  height: number
+  value?: number
+  children: LaidOutNode<T>[] | null
+  depthToLeaf = 0
+  row = 0
+  rowMin = 0
+  rowMax = 0
+  depthFraction = 0
+  branchLength = 0
+  collapsedBranchLength?: number
+
+  constructor(
+    source: HierarchyNode<T>,
+    readonly parent: LaidOutNode<T> | null,
+    private readonly frame: LayoutFrame,
+  ) {
+    this.data = source.data
+    this.depth = source.depth
+    this.height = source.height
+    this.value = source.value
+    this.children = source.children ? [] : null
+  }
+
+  private get pxPerBranchLength() {
+    const { scale, rootToTipLength } = this.frame
+    return rootToTipLength ? scale.treeWidth / rootToTipLength : 0
+  }
+
+  get x() {
+    return this.row * this.frame.scale.rowHeight
+  }
+
+  get xMin() {
+    return this.rowMin * this.frame.scale.rowHeight
+  }
+
+  get xMax() {
+    return this.rowMax * this.frame.scale.rowHeight
+  }
+
+  get y() {
+    return this.depthFraction * this.frame.scale.treeWidth
+  }
+
+  get len() {
+    return this.branchLength * this.pxPerBranchLength
+  }
+
+  get collapsedTipXFar() {
+    return this.collapsedBranchLength === undefined
+      ? undefined
+      : this.collapsedBranchLength * this.pxPerBranchLength
+  }
+}
+
+/**
+ * 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.
+ */
+export function layoutTree<T extends { length?: number }>(
+  root: HierarchyNode<T>,
+  scale: TreeScale,
+) {
+  const frame: LayoutFrame = { scale, rootToTipLength: 0 }
+  const nodes: LaidOutNode<T>[] = []
+  const leafNodes: LaidOutNode<T>[] = []
+  const rootHeight = root.height
+  const stack: { source: HierarchyNode<T>; parent: LaidOutNode<T> | null }[] = [
+    { source: root, parent: null },
+  ]
+  while (stack.length > 0) {
+    const { source, parent } = stack.pop()!
+    const node = new LaidOutNode(source, parent, frame)
+    nodes.push(node)
+    node.depthFraction =
+      rootHeight === 0 ? 1 : (source.depth - root.depth) / rootHeight
+    if (parent) {
+      parent.children!.push(node)
+      node.branchLength =
+        parent.branchLength + Math.max(source.data.length || 0, 0)
+      frame.rootToTipLength = Math.max(frame.rootToTipLength, node.branchLength)
+    }
+    if (source._children) {
+      node.collapsedBranchLength =
+        node.branchLength + collapsedSubtreeMaxLength(source)
+    }
+    if (source.children) {
+      for (let i = source.children.length - 1; i >= 0; i--) {
+        stack.push({ source: source.children[i]!, parent: node })
+      }
+    } else {
+      node.row = leafNodes.length + 0.5
+      node.depthToLeaf = source.depthToLeaf ?? 0
+      leafNodes.push(node)
+    }
+  }
+
+  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
+      let depthToLeaf = 0
+      for (const child of node.children) {
+        sum += child.row
+        min = Math.min(min, child.rowMin)
+        max = Math.max(max, child.rowMax)
+        depthToLeaf = Math.max(depthToLeaf, 1 + child.depthToLeaf)
+      }
+      node.row = sum / node.children.length
+      node.rowMin = min
+      node.rowMax = max
+      node.depthToLeaf = depthToLeaf
+    } else {
+      node.rowMin = node.row
+      node.rowMax = node.row
+    }
+  }
+  return {
+    root: nodes[0]!,
+    leaves: leafNodes,
+    rootToTipLength: frame.rootToTipLength,
+  }
+}
+
 export function collapse<T>(node: HierarchyNode<T>) {
   if (node.children) {
     // memoize the real subtree depth onto the node before detaching its

package/src/index.ts

@@ -36,7 +36,7 @@ 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'
+export type { HierarchyNode, LaidOutNode, TreeScale } 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'
@@ -60,13 +60,16 @@ export type {
   Cell,
   Clade,
   CladeMark,
+  ColorScheme,
   ColumnTrackSpec,
   DomainBand,
   Encoding,
   EncodingChannel,
+  Feature,
   Highlight,
   Legend,
   LegendEntry,
+  MsaSelection,
   Node,
   MappedStructure,
   NodeWithIds,
@@ -80,12 +83,16 @@ export type {
   ResolvedEncoding,
   ResolvedHighlight,
   ResolvedRowPanel,
+  ResolvedSelection,
+  RowDataInput,
   RowPanelSpec,
   RowResidue,
   StructureResidue,
   TextTrackModel,
   TidyDomainAnnotation,
   TrackKind,
+  TreeOrder,
+  TreeRoot,
   UnshareableData,
   Viewport,
 } from './types.ts'

package/src/model/DataModel.ts

@@ -9,7 +9,7 @@ import { maxInlineSnapshotBytes } from '../constants.ts'
  * data will not be persisted in saved session snapshots, it will be fetched
  * from msaFilehandle at startup
  */
-export function DataModelF() {
+export function DataModelF(maxInlineBytes = maxInlineSnapshotBytes) {
   return types
     .model({
       /**
@@ -56,12 +56,12 @@ export function DataModelF() {
       },
     }))
     .postProcessSnapshot(snap =>
-      // drops any field over maxInlineSnapshotBytes; the parent model's
+      // drops any field over maxInlineBytes; the parent model's
       // `unshareableData` reports what was dropped
       Object.fromEntries(
         Object.entries(snap).map(([key, text]) => [
           key,
-          text && text.length > maxInlineSnapshotBytes ? undefined : text,
+          text && text.length > maxInlineBytes ? undefined : text,
         ]),
       ),
     )

package/src/model/msaModel.ts

@@ -29,6 +29,13 @@ export function MSAModelF() {
        */
       colorSchemeName: stripDefault(types.string, defaultColorSchemeName),
 
+      /**
+       * #property
+       * a color per residue letter, which replaces the `colorSchemeName` table
+       * while set. A letter the map leaves out takes no color
+       */
+      customColorScheme: types.frozen<Record<string, string> | undefined>(),
+
       /**
        * #property
        * show a tooltip with the hovered column's value for a track while
@@ -49,10 +56,21 @@ export function MSAModelF() {
     .actions(self => ({
       /**
        * #action
-       * set color scheme name
+       * pick a scheme from the built-in table, which clears
+       * `customColorScheme`
        */
       setColorSchemeName(name: string) {
         self.colorSchemeName = name
+        self.customColorScheme = undefined
+      },
+
+      /**
+       * #action
+       * color residues from a map of letter to color, or pass undefined to
+       * return to `colorSchemeName`
+       */
+      setCustomColorScheme(map?: Record<string, string>) {
+        self.customColorScheme = map
       },
 
       /**

package/src/model/treeModel.ts

@@ -8,12 +8,16 @@ import {
   defaultLabelsAlignRight,
   defaultOverviewHeight,
   defaultShowBranchLen,
+  defaultTreeOrder,
   defaultShowTreeOverview,
   defaultTreeAreaWidth,
   defaultTreeWidth,
+  treeOrders,
 } from '../constants.ts'
 import { stripDefault } from '../stripDefault.ts'
 
+import type { TreeOrder } from '../types.ts'
+
 /**
  * #stateModel Tree
  */
@@ -51,6 +55,17 @@ export function TreeModelF() {
        */
       showBranchLen: stripDefault(types.boolean, defaultShowBranchLen),
 
+      /**
+       * #property
+       * the order each node's children draw in: `branchLength` (shortest
+       * first), `input` (as the file gives them), `ladderize` (fewest tips
+       * first) or `ladderizeReverse` (most tips first)
+       */
+      treeOrder: stripDefault(
+        types.enumeration<TreeOrder>('TreeOrder', [...treeOrders]),
+        defaultTreeOrder,
+      ),
+
       /**
        * #property
        * draw tree, boolean
@@ -133,6 +148,13 @@ export function TreeModelF() {
         self.showBranchLen = arg
       },
 
+      /**
+       * #action
+       */
+      setTreeOrder(order: TreeOrder) {
+        self.treeOrder = order
+      },
+
       /**
        * #action
        */