react-msaview 6.2.2 → 6.3.0

package/src/exportFileName.ts

@@ -0,0 +1,20 @@
+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.
+ */
+export function exportFileName(
+  location: FileLocation | undefined,
+  extension: string,
+) {
+  const loc = location as
+    { uri?: string; localPath?: string; name?: string } | undefined
+  const path = loc?.uri ?? loc?.localPath ?? loc?.name
+  const base = path
+    ?.split(/[?#]/)[0]
+    ?.split(/[/\\]/)
+    .pop()
+    ?.replace(/\.[^.]*$/, '')
+  return `${base || 'image'}.${extension}`
+}

package/src/headlessRenderEnv.ts

@@ -73,8 +73,14 @@ export class HeadlessDOMPoint {
  * 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.
+ *
+ * `contextExtras` adds to the context a test hands out -- the raster test
+ * supplies the ImageData methods that make the export take its image path.
  */
-export function installHeadlessRenderEnv(win: unknown = globalThis) {
+export function installHeadlessRenderEnv(
+  win: unknown = globalThis,
+  contextExtras: Partial<CanvasRenderingContext2D> = {},
+) {
   const g = globalThis as Record<string, unknown>
   g.DOMMatrix = HeadlessDOMMatrix
   g.DOMPoint = HeadlessDOMPoint
@@ -82,17 +88,20 @@ export function installHeadlessRenderEnv(win: unknown = globalThis) {
     .HTMLCanvasElement
   canvas.prototype.getContext = function () {
     let font = '10px sans-serif'
-    return {
-      get font() {
-        return font
-      },
-      set font(v: string) {
-        font = v
+    return Object.assign(
+      {
+        get font() {
+          return font
+        },
+        set font(v: string) {
+          font = v
+        },
+        measureText: (t: string) => ({
+          width: t.length * (Number.parseFloat(font) || 10) * CHAR_WIDTH_RATIO,
+        }),
       },
-      measureText: (t: string) => ({
-        width: t.length * (Number.parseFloat(font) || 10) * CHAR_WIDTH_RATIO,
-      }),
-    } as unknown as CanvasRenderingContext2D
+      contextExtras,
+    ) as unknown as CanvasRenderingContext2D
   } as unknown as typeof HTMLCanvasElement.prototype.getContext
 }
 

package/src/highlights.test.ts

@@ -0,0 +1,70 @@
+// @vitest-environment jsdom
+import { expect, test } from 'vitest'
+
+import MSAModelF from './model.ts'
+
+// seq2 skips columns 3-4 of the alignment, so its residue 3 sits at global
+// column 5 (1-based). The all-gap column 4 is what hideGaps removes.
+const msa = `>seq1
+AC-DEFG
+>seq2
+AC--EFG
+>seq3
+AC-DEFG`
+
+function makeModel(highlights: Record<string, unknown>[]) {
+  const model = MSAModelF().create({
+    id: 'highlights-test',
+    type: 'MsaView',
+    msaFormat: 'fasta',
+    data: { msa },
+    highlights,
+  })
+  model.setWidth(800)
+  return model
+}
+
+test('a column span is 1-based and lands on 0-based visible columns', () => {
+  const model = makeModel([{ start: 2, end: 4, label: 'x' }])
+  expect(model.resolvedHighlights).toEqual([
+    { startCol: 1, endCol: 3, rowIndices: [], label: 'x', color: undefined },
+  ])
+})
+
+test('a residue span projects through the named row', () => {
+  const model = makeModel([{ row: 'seq2', start: 3, end: 4 }])
+  expect(model.resolvedHighlights[0]).toMatchObject({ startCol: 4, endCol: 5 })
+})
+
+test('hidden columns shift a span and drop one they swallow whole', () => {
+  const model = makeModel([
+    { start: 5, end: 6, label: 'after' },
+    { start: 3, end: 3, label: 'gone' },
+    { row: 'seq2', start: 2, end: 3, label: 'across' },
+  ])
+  model.setHideGaps(true)
+  model.setAllowedGappyness(50)
+  expect(model.blanks).toEqual([2])
+  expect(
+    model.resolvedHighlights.map(h => [h.label, h.startCol, h.endCol]),
+  ).toEqual([
+    ['after', 3, 4],
+    ['across', 1, 3],
+  ])
+})
+
+test('a row set resolves to row indices and ignores unknown names', () => {
+  const model = makeModel([{ rows: ['seq3', 'nope', 'seq1'], color: 'red' }])
+  expect(model.resolvedHighlights).toEqual([
+    { rowIndices: [2, 0], label: undefined, color: 'red' },
+  ])
+  expect(makeModel([{ rows: ['nope'] }]).resolvedHighlights).toEqual([])
+})
+
+test('setHighlights replaces the list and reset clears it', () => {
+  const model = makeModel([])
+  model.setHighlights([{ start: 1, end: 1 }])
+  expect(model.highlights).toHaveLength(1)
+  model.reset()
+  expect(model.highlights).toHaveLength(0)
+})

package/src/impgRender.test.tsx

@@ -8,16 +8,14 @@
 // then renders <MSAView model/>. This exercises that path headlessly via the
 // public renderToSvg export. Polyfills mirror scripts/generateFigures.tsx.
 import { createJBrowseTheme } from '@jbrowse/core/ui/theme'
-import { enableStaticRendering } from 'mobx-react'
 import { beforeAll, expect, test } from 'vitest'
 
-import { installHeadlessRenderEnv } from './headlessRenderEnv.ts'
 import MSAModelF from './model.ts'
 import { renderToSvg } from './renderToSvg.tsx'
+import { installSvgTestEnv } from './svgTestUtil.ts'
 
 beforeAll(() => {
-  enableStaticRendering(true)
-  installHeadlessRenderEnv()
+  installSvgTestEnv()
 })
 
 // representative `impg query -o fasta-aln` block: PanSN names with region

package/src/index.ts

@@ -6,6 +6,7 @@
 // members they rely on (e.g. mouseCol/setMousePos, setHighlightedColumns,
 // seqPosToVisibleCol/visibleColToSeqPos) are flagged inline in model.ts.
 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 {
@@ -30,10 +31,13 @@ export type {
   Annotation,
   BasicTrack,
   BasicTrackModel,
+  ColumnTrackSpec,
   DomainBand,
+  Highlight,
   Node,
   NodeWithIds,
   NodeWithIdsAndLength,
+  ResolvedHighlight,
   TextTrackModel,
   TidyDomainAnnotation,
 } from './types.ts'

package/src/model.ts

@@ -50,6 +50,7 @@ import {
   segmentShades,
 } from './constants.ts'
 import { createPaletteMap } from './createPaletteMap.ts'
+import { exportFileName } from './exportFileName.ts'
 import { fetchTextWithProgress, isAbortError } from './fetchUtils.ts'
 import { flatToTree } from './flatToTree.ts'
 import {
@@ -85,20 +86,29 @@ import {
 import { buildSeqPosIndex } from './seqPosToGlobalCol.ts'
 import { maxBitsFor } from './sequenceLogo.ts'
 import { stripDefault } from './stripDefault.ts'
-import { computeRowInsertions, len, skipBlanks, transform } from './util.ts'
+import {
+  computeRowInsertions,
+  dropBlanks,
+  len,
+  skipBlanks,
+  transform,
+} from './util.ts'
 import { saveAs } from './vendor/fileSaver.ts'
 
 import type { HierarchyNode } from './hierarchy.ts'
+import type { ExportSvgOptions } from './renderToSvg.tsx'
 import type {
   Annotation,
   BasicTrack,
+  ColumnTrackSpec,
   DomainBand,
+  Highlight,
   NodeWithIds,
   NodeWithIdsAndLength,
+  ResolvedHighlight,
 } from './types.ts'
 import type { FileLocation as FileLocationType } from '@jbrowse/core/util/types'
 import type { Instance } from '@jbrowse/mobx-state-tree'
-import type { Theme } from '@mui/material'
 import type { InterProScanResults } from 'msa-parsers'
 
 function parseTreeText(text: string) {
@@ -113,6 +123,17 @@ function parseTreeText(text: string) {
 // asked for.
 const defaultOffTracks = new Set(['sequence-logo'])
 
+// a data track over this size stays in the live model but leaves the snapshot,
+// the same rule DataModel applies to an inline document
+const maxColumnTrackSnapshotBytes = 50_000
+
+function smallColumnTracks(tracks?: ColumnTrackSpec[]) {
+  const kept = tracks?.filter(
+    t => JSON.stringify(t).length <= maxColumnTrackSnapshotBytes,
+  )
+  return kept?.length ? { columnTracks: kept } : {}
+}
+
 /**
  * The snapshot properties reset() carries across a return to the import form:
  * display preferences and layout, nothing derived from the loaded file.
@@ -320,6 +341,16 @@ function stateModelFactory() {
          * hidden-by-default track adds nothing to the shared URL.
          */
         turnedOffTracks: stripDefault(types.map(types.boolean), {}),
+        /**
+         * #property
+         * tracks supplied as data rather than computed from the alignment:
+         * per-column values drawn as bars, or a per-column string drawn as a
+         * text track. See docs/layers.md
+         */
+        columnTracks: stripDefault(
+          types.array(types.frozen<ColumnTrackSpec>()),
+          [],
+        ),
 
         /**
          * #property
@@ -349,6 +380,14 @@ function stateModelFactory() {
          * in afterCreate.
          */
         highlightColumns: types.frozen<number[] | undefined>(),
+        /**
+         * #property
+         * labeled highlights in 1-based inclusive coordinates: a column span
+         * `{start, end}`, a residue span `{row, start, end}` of a named row,
+         * or a row set `{rows}`, each with an optional `label` and `color`.
+         * Persists in the snapshot, so a computed answer travels in the URL.
+         */
+        highlights: stripDefault(types.array(types.frozen<Highlight>()), []),
       }),
     )
     .volatile(() => ({
@@ -559,6 +598,12 @@ function stateModelFactory() {
       setHighlightedColumns(columns?: number[]) {
         self.highlightedColumns = columns
       },
+      /**
+       * #action
+       */
+      setHighlights(highlights: Highlight[]) {
+        self.highlights.replace(highlights)
+      },
       /**
        * #action
        * toggle the annotation overlay on the alignment
@@ -1527,6 +1572,12 @@ function stateModelFactory() {
         self.scrollX = clamp(n, self.maxScrollX, 0)
       },
 
+      /**
+       * #action
+       */
+      setColumnTracks(tracks: ColumnTrackSpec[]) {
+        self.columnTracks.replace(tracks)
+      },
       /**
        * #action
        */
@@ -1628,6 +1679,65 @@ function stateModelFactory() {
           }))
       },
 
+      /**
+       * #getter
+       * a data track's values or string, projected from its row's residues
+       * onto alignment columns when it names a row
+       */
+      get columnTrackContent() {
+        const { MSA, blanks, hideGapsEffective } = self
+        const width = MSA?.getWidth() ?? 0
+        const project = <T>(track: ColumnTrackSpec, items: T[], fill: T) => {
+          if (!track.row) {
+            return items
+          }
+          const out = Array.from({ length: width }, () => fill)
+          const index = self.seqPosGlobalColIndex.get(track.row)
+          items.forEach((item, seqPos) => {
+            const col = index?.[seqPos]
+            if (col !== undefined) {
+              out[col] = item
+            }
+          })
+          return out
+        }
+        const skip = <T>(items: T[]) =>
+          hideGapsEffective ? dropBlanks(blanks, items) : items
+        return new Map<string, { values?: number[]; data?: string }>(
+          self.columnTracks.map(track => {
+            if (track.kind === 'bar') {
+              const max = track.max ?? 1
+              const values = skip(project(track, track.values ?? [], 0)).map(
+                v => Math.min(1, Math.max(0, v / max)),
+              )
+              return [track.id, { values }] as const
+            }
+            const data = skip(project(track, (track.data ?? '').split(''), ' '))
+            return [track.id, { data: data.join('') }] as const
+          }),
+        )
+      },
+      /**
+       * #getter
+       */
+      get columnTrackModels(): BasicTrack[] {
+        return self.columnTracks.map(track => ({
+          model: {
+            id: track.id,
+            name: track.name,
+            kind: track.kind,
+            height:
+              track.height ??
+              (track.kind === 'bar'
+                ? self.conservationTrackHeight
+                : self.rowHeight),
+            barColor: track.color,
+            customColorScheme: track.colors,
+            data: this.columnTrackContent.get(track.id)?.data,
+          },
+          ReactComponent: TrackBlocks,
+        }))
+      },
       /**
        * #getter
        */
@@ -1654,6 +1764,7 @@ function stateModelFactory() {
         }
         return [
           ...this.adapterTrackModels,
+          ...this.columnTrackModels,
           ...[
             conservationTrack,
             ...(self.sequenceType === 'amino'
@@ -2047,6 +2158,51 @@ function stateModelFactory() {
         return runs
       },
 
+      /**
+       * #getter
+       * `highlights` projected onto what is on screen: residue spans go
+       * through the named row's gap structure, column spans through the
+       * hidden-column list, and a span that lands entirely on hidden columns
+       * is dropped. Row names that match no row are ignored.
+       */
+      get resolvedHighlights(): ResolvedHighlight[] {
+        const { blanks, rowNamesSet, rowMap } = self
+        const toVisible = (globalCol: number) => {
+          const visible = self.globalColToVisibleCol(globalCol)
+          return visible ?? visibleColsBefore(blanks, globalCol)
+        }
+        return self.highlights.flatMap(
+          ({ row, rows, start, end, label, color }) => {
+            const base = { label, color }
+            if (rows) {
+              const rowIndices = rows
+                .map(name => rowNamesSet.get(name))
+                .filter(notEmpty)
+              return rowIndices.length ? [{ ...base, rowIndices }] : []
+            }
+            if (start === undefined || end === undefined) {
+              return []
+            }
+            let startGlobal = start - 1
+            let endGlobal = end - 1
+            if (row !== undefined) {
+              if (!rowMap.has(row)) {
+                return []
+              }
+              startGlobal = self.seqPosToGlobalCol(row, start - 1)
+              endGlobal = self.seqPosToGlobalCol(row, end - 1)
+            }
+            const startCol = toVisible(startGlobal)
+            const endVisible = self.globalColToVisibleCol(endGlobal)
+            const endCol =
+              endVisible ?? visibleColsBefore(blanks, endGlobal) - 1
+            return startCol <= endCol
+              ? [{ ...base, startCol, endCol, rowIndices: [] }]
+              : []
+          },
+        )
+      },
+
       /**
        * #getter
        * per-column summary statistics for the hovered column: consensus residue
@@ -2140,16 +2296,11 @@ function stateModelFactory() {
       /**
        * #action
        */
-      async exportSVG(opts: {
-        theme: Theme
-        includeMinimap?: boolean
-        includeTracks?: boolean
-        exportType: 'entire' | 'viewport'
-      }) {
+      async exportSVG(opts: ExportSvgOptions) {
         const { renderToSvg } = await import('./renderToSvg.tsx')
         const html = await renderToSvg(self as MsaViewModel, opts)
         const blob = new Blob([html], { type: 'image/svg+xml' })
-        saveAs(blob, 'image.svg')
+        saveAs(blob, exportFileName(self.msaFilehandle, 'svg'))
       },
       initFilter(arg: string) {
         if (!self.featureFilters.has(arg)) {
@@ -2443,11 +2594,12 @@ function stateModelFactory() {
         )
       },
     }))
-    .postProcessSnapshot(({ data, ...rest }) => ({
+    .postProcessSnapshot(({ data, columnTracks, ...rest }) => ({
       // per-property defaults are stripped by the stripDefault helper; the only thing
       // it can't express is this cross-field rule: drop inline tree/msa/metadata
       // when a sibling filehandle can refetch them, keeping sessions/URLs small
       ...rest,
+      ...smallColumnTracks(columnTracks),
       data: {
         ...(rest.treeFilehandle ? {} : { tree: data.tree }),
         ...(rest.msaFilehandle ? {} : { msa: data.msa }),

package/src/renderColumnTracksSvg.test.tsx

@@ -0,0 +1,108 @@
+// @vitest-environment jsdom
+import { createJBrowseTheme } from '@jbrowse/core/ui/theme'
+import { enableStaticRendering } from 'mobx-react'
+import { beforeAll, expect, test } from 'vitest'
+
+import { installHeadlessRenderEnv } from './headlessRenderEnv.ts'
+import MSAModelF from './model.ts'
+import { renderToSvg } from './renderToSvg.tsx'
+
+import type { ColumnTrackSpec } from './types.ts'
+
+beforeAll(() => {
+  enableStaticRendering(true)
+  installHeadlessRenderEnv()
+})
+
+const msa = '>s1\nACGT\n>s2\nACGT\n'
+const colWidth = 20
+const barColor = '#123456'
+
+function makeModel(columnTracks: ColumnTrackSpec[]) {
+  const model = MSAModelF().create({
+    type: 'MsaView',
+    msaFormat: 'fasta',
+    height: 400,
+    colWidth,
+    data: { msa },
+    columnTracks,
+  })
+  model.setWidth(1000)
+  model.toggleTrack('conservation')
+  return model
+}
+
+async function exportSvg(model: ReturnType<typeof makeModel>) {
+  return renderToSvg(model, {
+    theme: createJBrowseTheme(),
+    exportType: 'entire',
+    includeTracks: true,
+  })
+}
+
+function rectsFilled(svg: string, fill: string) {
+  return [...svg.matchAll(/<rect ([^>]*)\/?>/g)]
+    .map(m => m[1]!)
+    .filter(attrs => attrs.includes(`fill="${fill}"`))
+    .map(attrs => ({
+      x: Number(/x="([\d.-]+)"/.exec(attrs)?.[1]),
+      width: Number(/width="([\d.-]+)"/.exec(attrs)?.[1]),
+      height: Number(/height="([\d.-]+)"/.exec(attrs)?.[1]),
+    }))
+}
+
+test('a bar track from values exports one bar per column in its color', async () => {
+  const model = makeModel([
+    {
+      id: 'dnds',
+      name: 'dN/dS',
+      kind: 'bar',
+      values: [1, 0.5, 0, 0.25],
+      color: barColor,
+    },
+  ])
+  const bars = rectsFilled(await exportSvg(model), barColor).sort(
+    (a, b) => a.x - b.x,
+  )
+  const trackHeight = model.conservationTrackHeight
+  expect(bars.map(b => b.x)).toEqual([0, colWidth, colWidth * 2, colWidth * 3])
+  expect(bars.map(b => b.height)).toEqual([
+    trackHeight,
+    trackHeight / 2,
+    0,
+    trackHeight / 4,
+  ])
+  expect(svgNamesTrack(await exportSvg(model))).toContain('dN/dS')
+})
+
+test('a text track from data exports its letters and its own colors', async () => {
+  const model = makeModel([
+    {
+      id: 'frame',
+      name: 'Codon frame',
+      kind: 'text',
+      data: '1231',
+      colors: { 1: '#aaaaaa', 2: '#bbbbbb', 3: '#cccccc' },
+    },
+  ])
+  const svg = await exportSvg(model)
+  expect(
+    rectsFilled(svg, '#aaaaaa')
+      .map(b => b.x)
+      .sort((a, b) => a - b),
+  ).toEqual([0, colWidth * 3])
+  expect(rectsFilled(svg, '#bbbbbb').map(b => b.x)).toEqual([colWidth])
+  expect(svgNamesTrack(svg)).toContain('Codon frame')
+})
+
+test('a data track that is toggled off stays out of the export', async () => {
+  const model = makeModel([
+    { id: 'dnds', name: 'dN/dS', kind: 'bar', values: [1], color: barColor },
+  ])
+  model.toggleTrack('dnds')
+  expect(rectsFilled(await exportSvg(model), barColor)).toEqual([])
+})
+
+function svgNamesTrack(svg: string) {
+  return [...svg.matchAll(/<text[^>]*>([^<]*)<\/text>/g)].map(m => m[1])
+}

package/src/renderDomainsSvg.test.tsx

@@ -5,16 +5,13 @@
 // right. Polyfills mirror impgRender.test.tsx (svgcanvas needs
 // DOMMatrix/DOMPoint + a measureText).
 import { createJBrowseTheme } from '@jbrowse/core/ui/theme'
-import { enableStaticRendering } from 'mobx-react'
 import { beforeAll, expect, test } from 'vitest'
 
-import { installHeadlessRenderEnv } from './headlessRenderEnv.ts'
-import MSAModelF from './model.ts'
 import { renderToSvg } from './renderToSvg.tsx'
+import { createTestModel, installSvgTestEnv } from './svgTestUtil.ts'
 
 beforeAll(() => {
-  enableStaticRendering(true)
-  installHeadlessRenderEnv()
+  installSvgTestEnv()
 })
 
 const msa = `>seq1
@@ -27,14 +24,10 @@ function makeModel({
   start = 1,
   end = 5,
 }: { data?: string; start?: number; end?: number } = {}) {
-  const model = MSAModelF().create({
+  const model = createTestModel({
     id: 'domain-svg-test',
-    type: 'MsaView',
-    height: 400,
-    msaFormat: 'fasta',
     data: { msa: data },
   })
-  model.setWidth(800)
   model.setDomains({
     seq1: {
       xref: [{ id: 'seq1' }],
@@ -80,6 +73,28 @@ test('no legend column when domains are hidden', async () => {
   expect(await exportEntire(model)).not.toContain('Kinase')
 })
 
+test('the page grows to hold a key taller than the alignment', async () => {
+  const model = makeModel()
+  model.setDomains({
+    seq1: {
+      xref: [{ id: 'seq1' }],
+      matches: Array.from({ length: 12 }, (_, i) => ({
+        signature: {
+          entry: { name: `Dom${i}`, accession: `PF${i}`, description: '' },
+        },
+        locations: [{ start: 1, end: 5 }],
+      })),
+    },
+  })
+  expect(model.visibleDomainTypes).toHaveLength(12)
+  const keyHeight = 16 + 12 * 16
+  expect(model.totalHeight).toBeLessThan(keyHeight)
+
+  const svg = await exportEntire(model)
+  expect(svg).toContain(`height="${keyHeight}"`)
+  expect(/<svg[^>]*height="(\d+)"/.exec(svg)?.[1]).toBe(String(keyHeight))
+})
+
 test('a domain box past the on-screen block size still draws', async () => {
   // the export renders the alignment in one pass, so the overlay has to be told
   // how wide that pass is; falling back to the 500px on-screen block size culled