react-msaview 8.1.0 → 8.2.0

package/src/expandSpec.ts

@@ -0,0 +1,196 @@
+import type { ColumnTrackSpec, Highlight, Region } from './types.ts'
+
+/**
+ * `row: null` opts one entry out of the spec's `query` row, back to alignment
+ * columns.
+ */
+type RowChoice = { row?: string | null }
+
+export type HighlightShorthand =
+  | number
+  | string
+  | (Omit<Highlight, 'row'> & RowChoice)
+
+export type RegionShorthand = string | (Omit<Region, 'row'> & RowChoice)
+
+export type ColumnTrackShorthand = Omit<
+  ColumnTrackSpec,
+  'id' | 'kind' | 'row'
+> &
+  RowChoice & {
+    id?: string
+    kind?: ColumnTrackSpec['kind']
+    /** the 1-based position `values` or `data` begins at */
+    start?: number
+  }
+
+/**
+ * The short forms a hand-written or generated link can use. Every long form
+ * passes through unchanged, so a snapshot is also a valid spec.
+ */
+export interface MsaSpec {
+  /**
+   * The row the spec is about: sets `relativeTo`, and is the `row` of every
+   * highlight, region and column track that names none
+   */
+  query?: string
+  /** a url, or the alignment itself when it spans more than one line */
+  msa?: string
+  /** a url, or a newick string when it starts with "(" */
+  tree?: string
+  highlights?: HighlightShorthand[]
+  region?: RegionShorthand
+  columnTracks?: ColumnTrackShorthand[]
+  [key: string]: unknown
+}
+
+/**
+ * The label a single-residue shorthand highlight gets, filled in from the
+ * sequence when drawn: `175` on a row reading R there becomes "R175".
+ */
+export const residueLabel = '{residue}{position}'
+
+const span = /^(\d+)(?:-(\d+))?(?:\s+(.+))?$/
+
+function parseSpan(text: string, what: string) {
+  const match = span.exec(text.trim())
+  if (!match) {
+    throw new Error(
+      `${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] }
+}
+
+function withRow<T extends RowChoice>(entry: T, query?: string) {
+  const { row, ...rest } = entry
+  const resolved = row === undefined ? query : (row ?? undefined)
+  return resolved === undefined ? rest : { ...rest, row: resolved }
+}
+
+function expandHighlight(entry: HighlightShorthand, query?: string) {
+  if (typeof entry === 'object') {
+    return (
+      entry.rows
+        ? entry
+        : withRow(entry, entry.start === undefined ? undefined : query)
+    ) as Highlight
+  }
+  const { start, end, label } = parseSpan(String(entry), 'highlight')
+  const single = start === end && query !== undefined
+  return {
+    ...(query === undefined ? {} : { row: query }),
+    start,
+    end,
+    ...(label ? { label } : single ? { label: residueLabel } : {}),
+  }
+}
+
+function expandRegion(region: RegionShorthand, query?: string) {
+  if (typeof region === 'string') {
+    const { start, end } = parseSpan(region, 'region')
+    const parsed: Omit<Region, 'row'> & RowChoice = { start, end }
+    return withRow(parsed, query) as Region
+  }
+  return withRow(region, query) as Region
+}
+
+function slug(name: string) {
+  return name
+    .toLowerCase()
+    .replaceAll(/[^a-z0-9]+/g, '-')
+    .replaceAll(/^-|-$/g, '')
+}
+
+function kindOf(track: ColumnTrackShorthand) {
+  if (track.kind) {
+    return track.kind
+  }
+  if (track.values) {
+    return 'bar'
+  }
+  if (track.data !== undefined) {
+    return 'text'
+  }
+  if (track.arcs) {
+    return 'arc'
+  }
+  throw new Error(
+    `column track "${track.name}" has no values, data or arcs to take its kind from`,
+  )
+}
+
+function expandTrack(
+  track: ColumnTrackShorthand,
+  query: string | undefined,
+  ids: Set<string>,
+): ColumnTrackSpec {
+  const { start, ...rest } = track
+  const pad = start && start > 1 ? start - 1 : 0
+  let id = track.id ?? (slug(track.name) || 'track')
+  for (let n = 2; !track.id && ids.has(id); n++) {
+    id = `${slug(track.name) || 'track'}-${n}`
+  }
+  ids.add(id)
+  return {
+    ...(withRow(rest, query) as Omit<ColumnTrackSpec, 'id' | 'kind'>),
+    id,
+    kind: kindOf(track),
+    ...(pad && track.values
+      ? { values: [...Array<number>(pad).fill(0), ...track.values] }
+      : {}),
+    ...(pad && track.data !== undefined
+      ? { data: ' '.repeat(pad) + track.data }
+      : {}),
+  }
+}
+
+function isInlineMsa(msa: string) {
+  return msa.includes('\n')
+}
+
+function isInlineTree(tree: string) {
+  return tree.trimStart().startsWith('(')
+}
+
+function uri(location: string) {
+  return { uri: location, locationType: 'UriLocation' as const }
+}
+
+/**
+ * Expand the short forms of an MsaView spec into the snapshot the model takes.
+ * Idempotent, and a no-op on a spec that uses none of them.
+ */
+export function expandSpec(spec: MsaSpec): Record<string, unknown> {
+  const { query, msa, tree, highlights, region, columnTracks, ...rest } = spec
+  const data = {
+    ...(rest.data as Record<string, unknown> | undefined),
+    ...(msa !== undefined && isInlineMsa(msa) ? { msa } : {}),
+    ...(tree !== undefined && isInlineTree(tree) ? { tree } : {}),
+  }
+  const ids = new Set(
+    (columnTracks ?? []).map(t => t.id).filter(id => id !== undefined),
+  )
+  return {
+    ...rest,
+    ...(msa !== undefined && !isInlineMsa(msa)
+      ? { msaFilehandle: uri(msa) }
+      : {}),
+    ...(tree !== undefined && !isInlineTree(tree)
+      ? { treeFilehandle: uri(tree) }
+      : {}),
+    ...(Object.keys(data).length > 0 ? { data } : {}),
+    ...(query !== undefined && rest.relativeTo === undefined
+      ? { relativeTo: query }
+      : {}),
+    ...(highlights
+      ? { highlights: highlights.map(h => expandHighlight(h, query)) }
+      : {}),
+    ...(region === undefined ? {} : { region: expandRegion(region, query) }),
+    ...(columnTracks
+      ? { columnTracks: columnTracks.map(t => expandTrack(t, query, ids)) }
+      : {}),
+  }
+}

package/src/index.ts

@@ -18,6 +18,14 @@ export {
 // the row count above which calculateNeighborJoiningTreeFromMSA throws, for
 // hosts gating their own menu item
 export { maxNeighborJoiningRows } from './constants.ts'
+// the short forms a link or a script can write a view in; see docs/layers.md
+export { expandSpec, residueLabel } from './expandSpec.ts'
+export type {
+  ColumnTrackShorthand,
+  HighlightShorthand,
+  MsaSpec,
+  RegionShorthand,
+} from './expandSpec.ts'
 export { default as MSAView } from './components/Loading.tsx'
 export { default as MSAViewer } from './components/MSAViewer.tsx'
 export type { MSAViewerProps } from './components/MSAViewer.tsx'

package/src/model.ts

@@ -877,6 +877,14 @@ function stateModelFactory() {
          * Persists in the snapshot and the URL.
          */
         highlights: stripDefault(types.array(types.frozen<Highlight>()), []),
+        /**
+         * #property
+         * where the view opens, in `highlights` coordinates: `{row, start,
+         * end}` zooms onto residues of that row, `{start, end}` onto alignment
+         * columns. Applied once the alignment and any tree file have loaded,
+         * then cleared, so a reloaded session keeps the reader's own scroll.
+         */
+        region: types.frozen<Region | undefined>(),
         /**
          * #property
          * clades of the tree with a mark drawn over them. `mrca` names tips
@@ -1156,6 +1164,12 @@ function stateModelFactory() {
       setHighlightedColumns(columns?: number[]) {
         self.highlightedColumns = columns
       },
+      /**
+       * #action
+       */
+      setRegion(region?: Region) {
+        self.region = region
+      },
       /**
        * #action
        */
@@ -3621,6 +3635,26 @@ function stateModelFactory() {
         return runs
       },
 
+      /**
+       * #method
+       * a highlight label with `{residue}` and `{position}` filled in from the
+       * row's letter at `start`, which is how the `175` shorthand draws "R175"
+       */
+      fillHighlightLabel(label: string, row?: string, start?: number) {
+        if (!label.includes('{')) {
+          return label
+        }
+        const col =
+          row && start !== undefined
+            ? self.seqPosIndex(row)?.[start - 1]
+            : undefined
+        const residue =
+          row && col !== undefined ? (self.MSA?.getRow(row)[col] ?? '') : ''
+        return label
+          .replaceAll('{residue}', residue)
+          .replaceAll('{position}', start === undefined ? '' : String(start))
+      },
+
       /**
        * #getter
        * `highlights` projected onto what is on screen: residue spans go
@@ -3636,7 +3670,10 @@ function stateModelFactory() {
           ...Object.values(transientHighlights).flat(),
         ]
         return all.flatMap(({ row, rows, start, end, label, color }) => {
-          const base = { label, color }
+          const base = {
+            label: label && this.fillHighlightLabel(label, row, start),
+            color,
+          }
           if (rows) {
             const rowIndices = rows
               .map(name => rowNamesSet.get(name))
@@ -4081,6 +4118,25 @@ function stateModelFactory() {
           }),
         )
 
+        // zoomToRegion needs a width and resolves residues through the visible
+        // columns, so this waits for both, and for a tree file whose collapsed
+        // clades would hide columns and move the target after the zoom
+        addDisposer(
+          self,
+          autorun(() => {
+            const { region } = self
+            if (
+              region &&
+              self.viewInitialized &&
+              self.numColumns > 0 &&
+              !(self.treeFilehandle && !self.data.tree)
+            ) {
+              this.zoomToRegion(region)
+              self.setRegion(undefined)
+            }
+          }),
+        )
+
         // the matchMedia query is pinned to the current device pixel ratio, so
         // each change re-registers against the new one
         if (

package/src/version.ts

@@ -1 +1 @@
-export const version = '8.1.0'
+export const version = '8.2.0'