react-msaview 8.4.1 → 9.1.0

package/src/constants.ts

@@ -55,9 +55,14 @@ export const minLetterColWidth = 5
 // sub-row band or a features panel over small rows
 export const minFeatureLabelHeight = 9
 
-// Tree labels are measured once at this size and scaled to the current font
-// size, so a vertical zoom never re-measures the tree.
-export const labelReferenceFontSize = 16
+export function fontSizeFor(rowHeight: number) {
+  return Math.min(Math.max(6, rowHeight - 3), 18)
+}
+
+// The fitted tree area measures the tip labels and the clade labels at the
+// font a default row draws, so a vertical zoom leaves the alignment in place.
+// A larger font ellipsizes the labels.
+export const labelFitFontSize = fontSizeFor(defaultRowHeight)
 
 // Zoom limits, px per cell. maxCellSize caps both smooth zoom and the stepwise
 // zoom-in buttons (which otherwise grow unbounded). minColWidth/minRowHeight are
@@ -74,8 +79,14 @@ export const defaultShowColumnStats = true
 // Tree model defaults
 export const defaultDrawLabels = true
 export const defaultLabelsAlignRight = false
-export const defaultTreeAreaWidth = 400
-export const defaultTreeWidth = 300
+// The fitted tree area gives the tree pxPerTreeDepth per level of its depth,
+// between minTreeWidth and maxFitTreeWidth, beside the widest label, and takes
+// at most maxTreeAreaShare of a view with an alignment. Where the share binds,
+// the tree keeps minTreeWidth and the labels ellipsize.
+export const minTreeWidth = 70
+export const maxFitTreeWidth = 160
+export const pxPerTreeDepth = 10
+export const maxTreeAreaShare = 0.3
 export const defaultShowBranchLen = true
 export const treeOrders = [
   'branchLength',
@@ -93,7 +104,7 @@ 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.
+// seventy. See agent-docs/reference/neighbor-joining-scaling.md.
 export const maxNeighborJoiningRows = 500
 
 // The opacity a `rowTint` encoding draws its scale's color at, so the residues

package/src/element.ts

@@ -49,10 +49,6 @@ const ownAttributes = [
 // 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
@@ -188,9 +184,9 @@ export function defineMsaElement(tagName = 'jbrowse-msa') {
       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')),
+        msaUrl: this.getAttribute('msa-url') ?? undefined,
+        treeUrl: this.getAttribute('tree-url') ?? undefined,
+        gffUrl: this.getAttribute('gff-url') ?? undefined,
         colorScheme:
           this.#data.colorScheme ??
           this.getAttribute('color-scheme') ??

package/src/exportLayout.ts

@@ -0,0 +1,134 @@
+import { legendRows } from './components/msa/legendRows.ts'
+import { treeScaleBarHeight } from './constants.ts'
+
+import type { LegendRow } from './components/msa/legendRows.ts'
+import type { MsaViewModel } from './model.ts'
+import type { Theme } from '@mui/material'
+
+export interface ExportSvgOptions {
+  theme: Theme
+  includeMinimap?: boolean
+  includeTracks?: boolean
+  exportType: 'entire' | 'viewport'
+}
+
+// legend geometry, shared by the width calculation and the renderer so the
+// reserved column on the right exactly fits the drawn legends
+export const LEGEND_PAD = 8
+export const LEGEND_ROW_H = 16
+export const LEGEND_SWATCH = 12
+export const LEGEND_FONT = 12
+export const LEGEND_CHAR_W = 7
+
+export const LEGEND_MAX_W = 360
+export const LEGEND_TEXT_X = LEGEND_PAD + LEGEND_SWATCH + 6
+
+export function getLegendWidth(rows: LegendRow[]) {
+  const maxLen = rows.reduce((a, r) => Math.max(a, r.label.length), 0)
+  const w = LEGEND_TEXT_X + LEGEND_PAD + maxLen * LEGEND_CHAR_W
+  return Math.min(LEGEND_MAX_W, Math.max(120, w))
+}
+
+export function legendHeight(rows: LegendRow[]) {
+  return LEGEND_PAD * 2 + rows.length * LEGEND_ROW_H
+}
+
+// resolved sizes/offsets (in svg user units) for the chosen export, shared by
+// every layer; 'entire' renders the whole alignment unscrolled, 'viewport'
+// mirrors the live scroll position
+export interface Layout {
+  width: number
+  msaAreaWidth: number
+  height: number
+  contentHeight: number
+  trackHeight: number
+  // the band the minimap, the row panel headers and the tree overview stacked
+  // on the scale bar share across the top
+  topHeight: number
+  offsetX: number
+  offsetY: number
+  includeMinimap: boolean
+  legendWidth: number
+}
+
+export function getLayout(model: MsaViewModel, opts: ExportSvgOptions): Layout {
+  const {
+    scrollX,
+    scrollY,
+    totalWidth,
+    totalHeight,
+    effectiveTreeAreaWidth,
+    rowPanelsWidth,
+    rowPanelsHeaderHeight,
+    totalTrackAreaHeight,
+    minimapHeight,
+    msaAreaHeight,
+    msaCanvasWidth,
+    showHorizontalScrollbar,
+    treeOverviewHeight,
+    treeScaleBar,
+  } = model
+  const trackHeight = opts.includeTracks ? totalTrackAreaHeight : 0
+  // the minimap reflects the live viewport scroll position, so it's only
+  // meaningful for a viewport export, never for the entire alignment -- and
+  // only when the live view shows one at all, since a minimap over an alignment
+  // that already fits marks a viewport wider than the bar
+  const includeMinimap =
+    opts.exportType === 'viewport' &&
+    !!opts.includeMinimap &&
+    showHorizontalScrollbar
+  const rows = legendRows(model.legends)
+  const legendWidth = rows.length > 0 ? getLegendWidth(rows) : 0
+  const topHeight = Math.max(
+    includeMinimap ? minimapHeight : 0,
+    rowPanelsHeaderHeight,
+    treeOverviewHeight + (treeScaleBar ? treeScaleBarHeight : 0),
+  )
+  const gutterWidth = effectiveTreeAreaWidth + rowPanelsWidth
+
+  // width stays content-only; the legend occupies an extra column added at the
+  // svg root in MsaSvg. The viewport export takes the alignment canvas's own
+  // size rather than the widget's -- the widget box also covers the header, the
+  // resize handle and the scrollbars, and rendering that box exports rows and
+  // columns the scrollbars hide on screen
+  return opts.exportType === 'entire'
+    ? {
+        width: totalWidth + gutterWidth,
+        msaAreaWidth: totalWidth,
+        height: totalHeight + trackHeight + topHeight,
+        contentHeight: totalHeight,
+        trackHeight,
+        topHeight,
+        offsetX: 0,
+        offsetY: 0,
+        includeMinimap,
+        legendWidth,
+      }
+    : {
+        width: msaCanvasWidth + gutterWidth,
+        msaAreaWidth: msaCanvasWidth,
+        height: msaAreaHeight + topHeight + trackHeight,
+        contentHeight: msaAreaHeight,
+        trackHeight,
+        topHeight,
+        offsetX: -scrollX,
+        offsetY: -scrollY,
+        includeMinimap,
+        legendWidth,
+      }
+}
+
+/**
+ * the exported page's size: the layout plus the legend column, and as tall as
+ * the legend where the key outgrows a short alignment
+ */
+export function exportPageSize(model: MsaViewModel, layout: Layout) {
+  const { width, height, legendWidth, topHeight } = layout
+  return {
+    width: width + legendWidth,
+    height:
+      legendWidth > 0
+        ? Math.max(height, topHeight + legendHeight(legendRows(model.legends)))
+        : height,
+  }
+}

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'
@@ -29,6 +27,8 @@ export type {
 export { default as MSAView } from './components/Loading.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'
 export { mount } from './mount.tsx'
 export { defineMsaElement } from './element.ts'
 export { useMsaSvgFigure } from './useMsaSvgFigure.ts'
@@ -37,7 +37,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

package/src/measureTextCanvas.ts

@@ -1,7 +1,7 @@
 import { setFontSize } from './setFontSize.ts'
 
-// Cached across calls: labelWidthMap measures every leaf label on every layout,
-// and both createElement and getContext are far more expensive than measureText.
+// Cached across calls, since both createElement and getContext are far more
+// expensive than measureText.
 // `null` records that this environment has no 2d context, so the lookup is not
 // retried on every label.
 let ctxHandle: CanvasRenderingContext2D | null | undefined
@@ -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

package/src/model/treeModel.ts

@@ -10,8 +10,6 @@ import {
   defaultShowBranchLen,
   defaultTreeOrder,
   defaultShowTreeOverview,
-  defaultTreeAreaWidth,
-  defaultTreeWidth,
   treeOrders,
 } from '../constants.ts'
 import { stripDefault } from '../stripDefault.ts'
@@ -36,16 +34,19 @@ export function TreeModelF() {
 
       /**
        * #property
-       * width of the area the tree is drawn in, px
+       * width of the area the tree and its labels draw in, px. Undefined fits
+       * the area to the labels and the tree; `effectiveTreeAreaWidth` reads
+       * the width either way
        */
-      treeAreaWidth: stripDefault(types.number, defaultTreeAreaWidth),
+      treeAreaWidth: types.maybe(types.number),
 
       /**
        * #property
-       * width of the tree within the treeArea, px. automatically synced to
-       * fit within treeAreaWidth
+       * width of the tree within the tree area, px. Undefined gives the tree
+       * the area less the labels; `effectiveTreeWidth` reads the width either
+       * way
        */
-      treeWidth: stripDefault(types.number, defaultTreeWidth),
+      treeWidth: types.maybe(types.number),
 
       /**
        * #property
@@ -97,29 +98,24 @@ export function TreeModelF() {
        * 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)
-       * instead of using a fixed width. useful when there is no tree, so the
-       * label gutter isn't padded out to the default 400px
-       */
-      autoTreeAreaWidth: stripDefault(types.boolean, false),
     })
     .actions(self => ({
       /**
        * #action
-       * set tree area width (px)
+       * set the tree area width, px, or undefined to fit it to the labels and
+       * the tree. The tree then fills the area less the labels
        */
-      setTreeAreaWidth(n: number) {
-        self.treeAreaWidth = Math.round(n)
+      setTreeAreaWidth(n: number | undefined) {
+        self.treeAreaWidth = n === undefined ? undefined : Math.round(n)
+        self.treeWidth = undefined
       },
       /**
        * #action
-       * set tree width (px)
+       * set the tree width, px, or undefined to fill the tree area less the
+       * labels
        */
-      setTreeWidth(n: number) {
-        self.treeWidth = Math.round(n)
+      setTreeWidth(n: number | undefined) {
+        self.treeWidth = n === undefined ? undefined : Math.round(n)
       },
 
       /**
@@ -134,12 +130,6 @@ export function TreeModelF() {
       setDrawTree(arg: boolean) {
         self.drawTree = arg
       },
-      /**
-       * #action
-       */
-      setAutoTreeAreaWidth(arg: boolean) {
-        self.autoTreeAreaWidth = arg
-      },
 
       /**
        * #action
@@ -173,13 +163,6 @@ export function TreeModelF() {
       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
        */