react-msaview 9.2.0 → 9.4.0

package/src/constants.ts

@@ -4,6 +4,8 @@ import type { TreeOrder } from './types.ts'
 export const defaultRowHeight = 16
 export const defaultColWidth = 12
 export const defaultHeight = 550
+// the dividers' thickness, between the tree and the alignment and under the view
+export const resizeHandleWidth = 5
 export const defaultScrollX = 0
 export const defaultScrollY = 0
 export const defaultCurrentAlignment = 0

package/src/element.ts

@@ -1,5 +1,6 @@
 import { when } from 'mobx'
 
+import { defaultHeight, resizeHandleWidth } from './constants.ts'
 import { mount } from './mount.tsx'
 
 import type { MSAViewerProps } from './components/MSAViewer.tsx'
@@ -46,8 +47,13 @@ const ownAttributes = [
   'theme',
   'reference-row',
   'tree-area-width',
+  'loading',
 ] as const
 
+// how far outside the viewport a lazy element starts mounting, so the viewer
+// is drawing by the time the reader scrolls to it
+const lazyMargin = '200px'
+
 // the attributes a <nightingale-manager> writes on the elements it holds
 const nightingaleAttributes = ['display-start', 'display-end', 'highlight']
 
@@ -87,13 +93,17 @@ 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,
- * 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.
+ * theme, tree-area-width, reference-row and loading. Properties: msa, tree and
+ * gff text, features, colorScheme, highlights, columnTracks, residueMappings
+ * and selection. The colorScheme property takes a `{domain, range}` 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.
+ *
+ * `loading="lazy"` mounts the viewer once the element comes within 200 pixels
+ * of the viewport, as `<img loading="lazy">` loads its image. Until then the
+ * element shows its own children, such as an `<img>` of the first frame, and
+ * reserves the viewer's height.
  *
  * Inside a <nightingale-manager>, the element registers with it and speaks its
  * protocol: it follows the display-start, display-end and highlight attributes
@@ -110,6 +120,7 @@ export function defineMsaElement(tagName = 'jbrowse-msa') {
     static observedAttributes = [...ownAttributes, ...nightingaleAttributes]
 
     #viewer?: MountedViewer
+    #nearby?: IntersectionObserver
     #model?: MsaViewModel
     #manager?: NightingaleManager
     #cancelRange?: () => void
@@ -289,7 +300,22 @@ export function defineMsaElement(tagName = 'jbrowse-msa') {
       if (!this.style.display) {
         this.style.display = 'block'
       }
-      this.#viewer = mount(this, this.#props())
+      if (this.#lazy) {
+        const height =
+          numberAttribute(this.getAttribute('height')) ?? defaultHeight
+        this.style.minHeight = `${height + resizeHandleWidth}px`
+        this.#nearby = new IntersectionObserver(
+          entries => {
+            if (entries.some(entry => entry.isIntersecting)) {
+              this.#mount()
+            }
+          },
+          { rootMargin: lazyMargin },
+        )
+        this.#nearby.observe(this)
+      } else {
+        this.#mount()
+      }
       const manager = this.closest<NightingaleManager>('nightingale-manager')
       if (manager) {
         void customElements.whenDefined('nightingale-manager').then(() => {
@@ -301,7 +327,22 @@ export function defineMsaElement(tagName = 'jbrowse-msa') {
       }
     }
 
+    get #lazy() {
+      return (
+        this.getAttribute('loading') === 'lazy' &&
+        typeof IntersectionObserver !== 'undefined'
+      )
+    }
+
+    #mount() {
+      this.#nearby?.disconnect()
+      this.#nearby = undefined
+      this.#viewer ??= mount(this, this.#props())
+    }
+
     disconnectedCallback() {
+      this.#nearby?.disconnect()
+      this.#nearby = undefined
       this.#manager?.unregister(this)
       this.#manager = undefined
       this.#cancelRange?.()
@@ -323,6 +364,10 @@ export function defineMsaElement(tagName = 'jbrowse-msa') {
         }
       } else if (name === 'highlight') {
         this.#followHighlight()
+      } else if (name === 'loading') {
+        if (this.#nearby && !this.#lazy) {
+          this.#mount()
+        }
       } else {
         this.#viewer?.update(this.#props())
       }

package/src/featurePanels.ts

@@ -1,12 +1,8 @@
-import { notEmpty } from '@jbrowse/core/util'
-
 import { packDomainLanes } from './components/msa/packDomainLanes.ts'
 import { defaultFeaturePanelWidth } from './constants.ts'
 import { featureField } from './featureFields.ts'
-import { resolveScale } from './scales.ts'
 import { outlineColor } from './util.ts'
 
-import type { ScaleSpec } from './scales.ts'
 import type {
   Annotation,
   DomainBand,
@@ -16,7 +12,7 @@ import type {
 } from './types.ts'
 
 // the fill of a span under a scale that gives its value no color, such as a
-// gene a `map` over gene names leaves out
+// gene a `domain` of gene names leaves out
 const UNSCALED_FEATURE = '#d9d9d9'
 
 // the fraction of a span a following one may cover before it takes a lane of
@@ -247,23 +243,3 @@ export function featurePanelSpans({
     ]),
   )
 }
-
-// a scale over the values a field takes across every feature loaded, so hiding
-// a type in the filter dialog leaves the rest in their colors, and a legend of
-// the values the features drawn carry
-export function resolveFeatureScale(
-  field: string,
-  scale: ScaleSpec | undefined,
-  annotations: Annotation[],
-  drawn: Annotation[],
-) {
-  const valuesOf = (list: Annotation[]) =>
-    list.map(a => featureField(a, field)).filter(notEmpty)
-  const resolved = resolveScale(scale, valuesOf(annotations))
-  const shown = new Set(valuesOf(drawn))
-  return {
-    field,
-    ...resolved,
-    legend: resolved.legend.filter(entry => shown.has(entry.id)),
-  }
-}

package/src/ggplotPalettes.ts

@@ -72,10 +72,22 @@ export const namedPalettes: Record<string, readonly string[]> = {
   ],
 }
 
+// the spellings jbrowse-components' `paletteFromSpec` takes for two of them
+const aliases: Record<string, string> = {
+  okabeIto: 'okabeito',
+  tableau10: 'tableau',
+}
+
 /**
  * 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]
+  return name === undefined
+    ? undefined
+    : Object.hasOwn(namedPalettes, name)
+      ? namedPalettes[name]
+      : Object.hasOwn(aliases, name)
+        ? namedPalettes[aliases[name]!]
+        : undefined
 }

package/src/groupKeys.ts

@@ -0,0 +1,54 @@
+// copied from jbrowse-components packages/core/src/util/groupKeys.ts, which
+// @jbrowse/core 5.0.0-beta.9 ships but the hosts the plugin runs on do not
+
+const NUMERIC = /^-?\d+(\.\d+)?$/
+const DIGIT_RUNS = /\d+|\D+/g
+
+function compareRuns(a: string, b: string) {
+  const runsA = a.match(DIGIT_RUNS) ?? []
+  const runsB = b.match(DIGIT_RUNS) ?? []
+  const shared = Math.min(runsA.length, runsB.length)
+  for (let i = 0; i < shared; i++) {
+    const x = runsA[i]!
+    const y = runsB[i]!
+    if (x === y) {
+      continue
+    }
+    if (/^\d/.test(x) && /^\d/.test(y)) {
+      const nx = Number(x)
+      const ny = Number(y)
+      if (nx !== ny) {
+        return nx < ny ? -1 : 1
+      }
+      return x.length < y.length ? -1 : 1
+    }
+    return x < y ? -1 : 1
+  }
+  return runsA.length - runsB.length
+}
+
+/**
+ * Numbers first by value, then every other value run by run with digit runs
+ * by magnitude, so `2` before `10`, `chr2` before `chr10` and `2.3.2.1a`
+ * before `2.3.4.4b`. The empty value sorts last.
+ */
+export function compareGroupKeys(a: string, b: string) {
+  if (a === b) {
+    return 0
+  }
+  if (a === '' || b === '') {
+    return a === '' ? 1 : -1
+  }
+  const numA = NUMERIC.test(a)
+  const numB = NUMERIC.test(b)
+  if (numA !== numB) {
+    return numA ? -1 : 1
+  }
+  if (numA) {
+    const diff = Number(a) - Number(b)
+    if (diff !== 0) {
+      return diff < 0 ? -1 : 1
+    }
+  }
+  return compareRuns(a, b)
+}

package/src/index.ts

@@ -51,8 +51,19 @@ export type { InterProScanResults } from 'msa-parsers'
 export type { ColumnCounts } from './columnCounts.ts'
 export type { ColumnStats } from './columnStats.ts'
 export type { ZoomSnapshot } from './zoomSnapshot.ts'
-// the scale an encoding reads its field through, and what resolving one gives
-export type { ResolvedScale, ScaleSpec } from './scales.ts'
+// the color object a channel reads its field through, and what resolving one
+// gives
+export type {
+  ColorChannel,
+  ColorSpec,
+  LegacyColumnTrack,
+  LegacyEncoding,
+  LegacyRowPanel,
+  LegacyScale,
+  ResolvedScale,
+  ScaleTable,
+  SharedScale,
+} from './scales.ts'
 export type {
   Accession,
   Annotation,

package/src/model.ts

@@ -60,6 +60,7 @@ import {
   minRowHeight,
   minTreeWidth,
   pxPerTreeDepth,
+  resizeHandleWidth,
   rowPanelHeaderHeight,
   rowTintAlpha,
   scrollZoomAxes,
@@ -70,13 +71,12 @@ import {
 } from './constants.ts'
 import { createPaletteMap } from './createPaletteMap.ts'
 import { exportFileName } from './exportFileName.ts'
-import { featureName } from './featureFields.ts'
+import { featureField, featureName } from './featureFields.ts'
 import {
   colorByRow,
   featureColorMap,
   featureLabelMap,
   featurePanelSpans,
-  resolveFeatureScale,
   rowPanelWidth,
   stringFields,
 } from './featurePanels.ts'
@@ -102,7 +102,14 @@ import {
   visibleColToGlobalCol,
   visibleColsBefore,
 } from './rowCoordinateCalculations.ts'
-import { resolveScale } from './scales.ts'
+import {
+  colorTable,
+  declarationKey,
+  readColumnTrack,
+  readEncoding,
+  readRowPanel,
+  resolveShared,
+} from './scales.ts'
 import { buildSeqPosIndex } from './seqPosToGlobalCol.ts'
 import { maxBitsFor } from './sequenceLogo.ts'
 import {
@@ -136,6 +143,15 @@ import type { ColumnStats } from './columnStats.ts'
 import type { ScrollZoomAxis } from './constants.ts'
 import type { HierarchyNode } from './hierarchy.ts'
 import type { ExportSvgOptions } from './renderToSvg.tsx'
+import type {
+  ColorChannel,
+  LegacyColumnTrack,
+  LegacyEncoding,
+  LegacyRowPanel,
+  ScaleTable,
+  ScaleUse,
+  SharedScale,
+} from './scales.ts'
 import type {
   Annotation,
   Arc,
@@ -600,7 +616,11 @@ function stateModelFactory({
          * per-column string drawn as a text track. See docs/layers.md
          */
         columnTracks: stripDefault(
-          types.array(types.frozen<ColumnTrackSpec>()),
+          types.array(
+            types.snapshotProcessor(types.frozen<ColumnTrackSpec>(), {
+              preProcessor: readColumnTrack,
+            }),
+          ),
           [],
         ),
 
@@ -688,20 +708,35 @@ function stateModelFactory({
         clades: stripDefault(types.array(types.frozen<Clade>()), []),
         /**
          * #property
-         * what the viewer's own marks read from `rowData`:
-         * `{channel, field, scale?}` per channel, where `channel` is
-         * `tipLabel` or `rowTint`. See docs/layers.md
+         * what the viewer's own marks read from `rowData` or the feature
+         * table: `{channel, field, range?, domain?, title?}` per channel. The
+         * earlier `scale: {palette}` and `scale: {map}` read as `range` and
+         * `domain`. See docs/layers.md
          */
-        encodings: stripDefault(types.array(types.frozen<Encoding>()), []),
+        encodings: stripDefault(
+          types.array(
+            types.snapshotProcessor(types.frozen<Encoding>(), {
+              preProcessor: readEncoding,
+            }),
+          ),
+          [],
+        ),
         /**
          * #property
          * panels drawn between the tree and the alignment:
-         * `{kind: "strip", field, scale?, width?, header?}` colors one cell
-         * per row from a `rowData` field, and
+         * `{kind: "strip", field, range?, domain?, title?, width?, header?}`
+         * colors one cell per row from a `rowData` field, and
          * `{kind: "features", x, encoding?, transform?, width?, header?}`
          * draws the spans the GFF carries. See docs/layers.md
          */
-        rowPanels: stripDefault(types.array(types.frozen<RowPanelSpec>()), []),
+        rowPanels: stripDefault(
+          types.array(
+            types.snapshotProcessor(types.frozen<RowPanelSpec>(), {
+              preProcessor: readRowPanel,
+            }),
+          ),
+          [],
+        ),
       }),
     )
     .volatile(() => ({
@@ -765,9 +800,10 @@ function stateModelFactory({
       volatileWidth: undefined as number | undefined,
       /**
        * #volatile
-       * resize handle width between tree and msa area, px
+       * thickness of the dividers, between the tree and the alignment and under
+       * the view, px
        */
-      resizeHandleWidth: 5,
+      resizeHandleWidth,
 
       /**
        * #volatile
@@ -2310,7 +2346,7 @@ function stateModelFactory({
                 return [track.id, { arcs }] as const
               }
               if (track.kind === 'bar') {
-                const max = track.max ?? 1
+                const max = track.scales?.y?.domainMax ?? 1
                 const values = skip(project(track, track.values ?? [], 0)).map(
                   v => Math.min(1, Math.max(0, v / max)),
                 )
@@ -2361,7 +2397,12 @@ function stateModelFactory({
                   height: this.trackHeight(track.kind, heightKey, track.height),
                   barColor: track.color,
                   arcColor: track.color,
-                  customColorScheme: track.colors,
+                  customColorScheme: track.encoding?.color
+                    ? colorTable(track.encoding.color, [
+                        ...(track.encoding.color.domain ?? []),
+                        ...new Set(track.data),
+                      ])
+                    : undefined,
                   data: content?.data,
                   arcs: content?.arcs,
                 },
@@ -3418,8 +3459,8 @@ function stateModelFactory({
       /**
        * #action
        */
-      setColumnTracks(tracks: ColumnTrackSpec[]) {
-        self.columnTracks.replace(tracks)
+      setColumnTracks(tracks: (ColumnTrackSpec | LegacyColumnTrack)[]) {
+        self.columnTracks.replace(tracks.map(readColumnTrack))
       },
       /**
        * #action
@@ -3433,15 +3474,15 @@ function stateModelFactory({
        * #action
        * replace what the viewer's marks read from the row table
        */
-      setEncodings(encodings: Encoding[]) {
-        self.encodings.replace(encodings)
+      setEncodings(encodings: (Encoding | LegacyEncoding)[]) {
+        self.encodings.replace(encodings.map(readEncoding))
       },
       /**
        * #action
        * replace the panels drawn between the tree and the alignment
        */
-      setRowPanels(panels: RowPanelSpec[]) {
-        self.rowPanels.replace(panels)
+      setRowPanels(panels: (RowPanelSpec | LegacyRowPanel)[]) {
+        self.rowPanels.replace(panels.map(readRowPanel))
       },
       /**
        * #action
@@ -3554,12 +3595,20 @@ function stateModelFactory({
       /**
        * #getter
        * categorical feature types (InterPro domains and the like) that each get
-       * their own color and a legend entry
+       * their own color and a legend entry, in palette order: grouped by
+       * feature type, types in the order they first appear. A GenPept
+       * record's CDD Sites follow every Region, so the palette spends the
+       * colors after the domains' on the sites inside them
        */
       get categoricalDomainTypes() {
-        return [...self.annotationTypes.values()].filter(
+        const types = [...self.annotationTypes.values()].filter(
           d => !segmentFeatureTypes.has(d.featureType ?? ''),
         )
+        const typeOrder = [...new Set(types.map(d => d.featureType))]
+        return types.toSorted(
+          (a, b) =>
+            typeOrder.indexOf(a.featureType) - typeOrder.indexOf(b.featureType),
+        )
       },
       get fillPalette() {
         const segments = Object.fromEntries(
@@ -3643,42 +3692,41 @@ function stateModelFactory({
        * the categorical color keys drawn for this view, shared by the on-screen
        * legend overlay and the SVG export's reserved column. The domain overlay
        * produces the first, listing the `featureFill` scale where an encoding
-       * names one. Every field a row-table encoding or a row panel reads
-       * produces one more, so two channels over one field, or two strips over
-       * it, list that field once. A strip's `legend` names the title it lists
-       * under, so strips over eight fields with one set of colors list one
-       * legend between them
+       * names one. Every scale a row-table encoding or a row panel reads
+       * produces one more, keyed by its declaration, so two channels or two
+       * strips declaring one scale list it once, and strips over eight fields
+       * naming one `title` list one legend between them
        */
       get legends(): Legend[] {
         const { featureFillEncoding, fillPalette, visibleDomainTypes } = this
         const byKey = new Map<string, Legend>()
+        const ids = new Set<string>()
         // the accession palette keys on no field, so it takes a key of its own
         const add = (
-          field: string | undefined,
+          key: string | undefined,
+          title: string | undefined,
           entries: LegendEntry[],
-          id?: string,
+          overlay = false,
         ) => {
-          if (entries.length === 0) {
+          const k = key ?? 'domains'
+          if (entries.length === 0 || byKey.has(k)) {
             return
           }
-          const key = field === undefined ? 'domains' : `field:${field}`
-          const legend = byKey.get(key)
-          if (legend) {
-            const seen = new Set(legend.entries.map(e => e.id))
-            legend.entries.push(...entries.filter(e => !seen.has(e.id)))
-          } else {
-            byKey.set(key, {
-              id: id ?? (field === undefined ? 'domains' : `rowData-${field}`),
-              title: field ?? 'Domains',
-              entries: [...entries],
-            })
+          const base =
+            overlay || key === undefined ? 'domains' : `rowData-${title}`
+          let id = base
+          for (let n = 2; ids.has(id); n++) {
+            id = `${base}-${n}`
           }
+          ids.add(id)
+          byKey.set(k, { id, title: title ?? 'Domains', entries })
         }
         // the overlay draws the domain key; with no columns it draws nothing,
         // and a features panel taking the same colors lists them instead
         if (self.actuallyShowDomains && self.numColumns > 0) {
           add(
-            featureFillEncoding?.field,
+            featureFillEncoding?.key,
+            featureFillEncoding?.title,
             featureFillEncoding
               ? featureFillEncoding.legend
               : visibleDomainTypes.map(d => ({
@@ -3686,16 +3734,16 @@ function stateModelFactory({
                   label: d.name,
                   color: d.color ?? fillPalette[d.accession]!,
                 })),
-            'domains',
+            true,
           )
         }
-        for (const { channel, field, legend } of this.resolvedEncodings) {
+        for (const { channel, key, title, legend } of this.resolvedEncodings) {
           if (!featureChannels.has(channel)) {
-            add(field, legend)
+            add(key, title, legend)
           }
         }
-        for (const { legendTitle, legend } of this.rowPanelScales) {
-          add(legendTitle, legend)
+        for (const { legendKey, legendTitle, legend } of this.rowPanelScales) {
+          add(legendKey, legendTitle, legend)
         }
         return [...byKey.values()]
       },
@@ -4001,23 +4049,68 @@ function stateModelFactory({
        * table or the encodings, never per row per frame.
        */
       get resolvedEncodings(): ResolvedEncoding[] {
-        const rows = Object.values(self.rowData)
         return self.encodings.map(encoding => ({
           ...encoding,
-          ...(featureChannels.has(encoding.channel)
-            ? resolveFeatureScale(
-                encoding.field,
-                encoding.scale,
-                self.allAnnotations,
-                self.filteredAnnotations,
-              )
-            : resolveScale(
-                encoding.scale,
-                rows.map(row => row?.[encoding.field]).filter(notEmpty),
-              )),
+          ...this.scaleOf(
+            encoding,
+            featureChannels.has(encoding.channel) ? 'features' : 'rows',
+          ),
         }))
       },
 
+      /**
+       * #getter
+       * every color object the encodings and the row panels declare, keyed
+       * by declaration (`declarationKey`) and resolved once over the union
+       * of the values its records' fields take, so a value two strips share
+       * takes one color in both. A feature field reads every feature loaded,
+       * so hiding a type in the filter dialog leaves the rest in their
+       * colors, and its legend lists the values of the drawn features.
+       */
+      get resolvedScales() {
+        const rows = Object.values(self.rowData)
+        const featureValues = (list: Annotation[], field: string) =>
+          list.map(a => featureField(a, field)).filter(notEmpty)
+        const use = (channel: ColorChannel, table: ScaleTable): ScaleUse => ({
+          spec: channel,
+          field: channel.field,
+          table,
+          ...(table === 'rows'
+            ? {
+                values: rows.map(row => row?.[channel.field]).filter(notEmpty),
+              }
+            : {
+                values: featureValues(self.allAnnotations, channel.field),
+                shown: featureValues(self.filteredAnnotations, channel.field),
+              }),
+        })
+        return resolveShared([
+          ...self.encodings.map(encoding =>
+            use(
+              encoding,
+              featureChannels.has(encoding.channel) ? 'features' : 'rows',
+            ),
+          ),
+          ...self.rowPanels.flatMap(panel =>
+            panel.kind === 'strip'
+              ? [use(panel, 'rows')]
+              : panel.encoding?.color
+                ? [use(panel.encoding.color, 'features')]
+                : [],
+          ),
+        ])
+      },
+
+      /**
+       * #method
+       * the shared scale a record's color object resolves to
+       */
+      scaleOf(channel: ColorChannel, table: ScaleTable): SharedScale {
+        return this.resolvedScales.get(
+          declarationKey({ spec: channel, field: channel.field, table }),
+        )!
+      },
+
       /**
        * #getter
        * each row panel's scale resolved against the values its field takes,
@@ -4032,12 +4125,7 @@ function stateModelFactory({
           if (panel.kind === 'features') {
             const color = panel.encoding?.color
             const encoding = color
-              ? resolveFeatureScale(
-                  color.field,
-                  color.scale,
-                  self.allAnnotations,
-                  annotations,
-                )
+              ? { field: color.field, ...this.scaleOf(color, 'features') }
               : featureFillEncoding
             const label = panel.encoding?.label
             return {
@@ -4045,7 +4133,8 @@ function stateModelFactory({
               x: panel.x,
               header: panel.header ?? '',
               field: encoding?.field,
-              legendTitle: encoding?.field,
+              legendKey: encoding?.key,
+              legendTitle: encoding?.title,
               colors: color
                 ? featureColorMap(annotations, encoding, fillPalette)
                 : this.featureColors,
@@ -4061,17 +4150,13 @@ function stateModelFactory({
                 })),
             }
           }
-          const { colorOf, legend } = resolveScale(
-            panel.scale,
-            Object.values(rowData)
-              .map(row => row?.[panel.field])
-              .filter(notEmpty),
-          )
+          const { colorOf, legend, key, title } = this.scaleOf(panel, 'rows')
           return {
             kind: panel.kind,
             field: panel.field,
             header: panel.header ?? panel.field,
-            legendTitle: panel.legend ?? panel.field,
+            legendKey: key,
+            legendTitle: title,
             colors: colorByRow(rowData, panel.field, colorOf),
             legend,
           }