react-msaview 9.1.1 → 9.3.0

package/src/scales.ts

@@ -1,12 +1,42 @@
+import { colord } from 'colord'
+
 import { createPaletteMap } from './createPaletteMap.ts'
 import { paletteNamed } from './ggplotPalettes.ts'
+import { compareGroupKeys } from './groupKeys.ts'
 
-import type { LegendEntry } from './types.ts'
+import type {
+  ColorScheme,
+  ColumnTrackSpec,
+  Encoding,
+  LegendEntry,
+  RowPanelSpec,
+} from './types.ts'
 
-/** how a channel reads a field: a palette by name, or a color per value */
-export interface ScaleSpec {
-  palette?: string
-  map?: Record<string, string>
+/**
+ * The color object: the scale a channel reads its field through, the members
+ * jbrowse-components' displays declare (its ADR-151). The values the field
+ * takes are the scale's domain, `range` holds the colors they map onto, and
+ * the legend is the guide listing each value with its color.
+ *
+ * - `scale`: the kind, `categorical` when unset and the only kind so far
+ * - `domain`: values in legend order, each taking the `range` color at its own
+ *   index; the field's other values follow in natural order
+ * - `range`: a palette name (`ggplot`, `set1`, `dark2`, `okabeito`, `tableau`)
+ *   or a list of colors, which colors as many values as it holds
+ * - `title`: the legend's title, the field when unset
+ *
+ * Records declaring the same members, `title` included, share one scale.
+ */
+export interface ColorSpec {
+  scale?: 'categorical'
+  domain?: string[]
+  range?: string | string[]
+  title?: string
+}
+
+/** a channel record: a field read through a color object */
+export interface ColorChannel extends ColorSpec {
+  field: string
 }
 
 export interface ResolvedScale {
@@ -16,32 +46,245 @@ export interface ResolvedScale {
 }
 
 /**
- * The scale a channel reads its field through. `values` are the field's values,
- * in any order and with repeats; the domain is their distinct values sorted, so
- * a value keeps its color when rows are re-ordered, collapsed or filtered.
+ * The colors a `range` lists, read the way jbrowse-components'
+ * `paletteFromSpec` reads a string: a palette name gives undefined here, and a
+ * comma-separated list of colors gives the list
+ */
+function rangeList(range: ColorSpec['range']) {
+  if (typeof range !== 'string') {
+    return range
+  }
+  if (paletteNamed(range)) {
+    return undefined
+  }
+  const colors = range.split(/,(?![^(]*\))/).map(c => c.trim())
+  return colors.every(c => colord(c).isValid()) ? colors : undefined
+}
+
+function rangeColors(range: ColorSpec['range'], order: string[]) {
+  const list = rangeList(range)
+  return list
+    ? new Map(order.slice(0, list.length).map((value, i) => [value, list[i]!]))
+    : new Map(
+        Object.entries(
+          createPaletteMap(
+            order,
+            paletteNamed(typeof range === 'string' ? range : undefined),
+          ),
+        ),
+      )
+}
+
+/**
+ * The scale a channel reads its field through. `values` are the field's
+ * values, in any order and with repeats. The domain lists the values `domain`
+ * names first, then the rest in natural order, so a value keeps its color when
+ * rows are re-ordered, collapsed or filtered.
  *
- * `{map}` colors the values the producer named and leaves the rest uncolored.
- * `{palette}` takes the colors of a named palette, and a spec with neither
- * takes the ggplot palette of the domain's size. Every scale is categorical
- * today; a continuous one waits for a caller.
+ * A palette name, or no `range` at all, colors every value: past the end of
+ * the palette each takes an evenly spaced hue. A list of colors leaves the
+ * values past its end uncolored, so `{domain, range}` colors the values it
+ * names and no others.
  */
 export function resolveScale(
-  spec: ScaleSpec | undefined,
+  spec: ColorSpec | undefined,
   values: Iterable<string>,
 ): ResolvedScale {
-  const domain = [...new Set(values)].sort((a, b) => a.localeCompare(b))
-  const { map, palette } = spec ?? {}
-  const colors = map ?? createPaletteMap(domain, paletteNamed(palette))
-  const present = new Set(domain)
-  const labels = map ? Object.keys(map).filter(v => present.has(v)) : domain
+  const present = new Set(values)
+  const listed = new Set(spec?.domain)
+  const order = [
+    ...listed,
+    ...[...present].filter(v => !listed.has(v)).sort(compareGroupKeys),
+  ]
+  const colors = rangeColors(spec?.range, order)
   return {
     kind: 'categorical',
-    colorOf: (value: string) => colors[value],
-    // a categorical value is its own label, and the id a legend keys on
-    legend: labels.map(value => ({
-      id: value,
-      label: value,
-      color: colors[value]!,
-    })),
+    colorOf: (value: string) => colors.get(value),
+    legend: order
+      .filter(value => present.has(value) && colors.has(value))
+      .map(value => ({ id: value, label: value, color: colors.get(value)! })),
   }
 }
+
+/** which table a record's field is read from */
+export type ScaleTable = 'rows' | 'features'
+
+/**
+ * One record's use of a color object: the values its field takes in its
+ * table, and for the feature table the values the drawn features carry, which
+ * the legend lists
+ */
+export interface ScaleUse {
+  spec: ColorSpec
+  field: string
+  table: ScaleTable
+  values: string[]
+  shown?: string[]
+}
+
+export interface SharedScale extends ResolvedScale {
+  key: string
+  title: string
+}
+
+/**
+ * The key records share a scale under: the table and the members as declared,
+ * with `title` standing in for the field. Two strips over one palette with no
+ * title read two fields and list two legends; naming one title gives them one
+ * scale and one legend.
+ */
+export function declarationKey({
+  spec,
+  field,
+  table,
+}: Pick<ScaleUse, 'spec' | 'field' | 'table'>) {
+  const { scale = 'categorical', domain, range, title = field } = spec
+  return JSON.stringify([table, scale, domain, range, title])
+}
+
+/**
+ * Resolves each declaration once over the union of its records' values, so a
+ * value two fields share takes one color in both
+ */
+export function resolveShared(uses: ScaleUse[]) {
+  const groups = new Map<string, ScaleUse[]>()
+  for (const use of uses) {
+    const key = declarationKey(use)
+    groups.set(key, [...(groups.get(key) ?? []), use])
+  }
+  return new Map(
+    [...groups].map(([key, group]) => {
+      const { spec, field } = group[0]!
+      const resolved = resolveScale(
+        spec,
+        group.flatMap(u => u.values),
+      )
+      const shown = group[0]!.shown
+        ? new Set(group.flatMap(u => u.shown ?? []))
+        : undefined
+      const scale: SharedScale = {
+        ...resolved,
+        key,
+        title: spec.title ?? field,
+        legend: shown
+          ? resolved.legend.filter(entry => shown.has(entry.id))
+          : resolved.legend,
+      }
+      return [key, scale] as const
+    }),
+  )
+}
+
+/** the spelling a color object had before ADR-151's: `{palette}` or `{map}` */
+export interface LegacyScale {
+  palette?: string
+  map?: Record<string, string>
+}
+
+/** a record as an older snapshot, R or Python may write it */
+export type LegacyColor<T extends ColorSpec> = Omit<T, 'scale'> & {
+  scale?: ColorSpec['scale'] | LegacyScale
+  legend?: string
+}
+
+/**
+ * Lifts the earlier spelling onto the color object: `{palette: p}` reads as
+ * `{range: p}`, `{map: m}` as `{domain: keys(m), range: values(m)}`, and a
+ * strip's `legend` as `title`. A member written in the new spelling wins.
+ */
+export function readColor<T extends ColorSpec>(record: LegacyColor<T>): T {
+  const { scale, legend, ...rest } = record
+  if (typeof scale !== 'object' && legend === undefined) {
+    return record as T
+  }
+  const lifted: ColorSpec =
+    typeof scale !== 'object'
+      ? scale === undefined
+        ? {}
+        : { scale }
+      : scale.map
+        ? { domain: Object.keys(scale.map), range: Object.values(scale.map) }
+        : scale.palette === undefined
+          ? {}
+          : { range: scale.palette }
+  return {
+    ...(legend === undefined ? {} : { title: legend }),
+    ...lifted,
+    ...rest,
+  } as unknown as T
+}
+
+export type LegacyEncoding = LegacyColor<Encoding>
+
+export function readEncoding(encoding: Encoding | LegacyEncoding) {
+  return readColor<Encoding>(encoding)
+}
+
+export type LegacyRowPanel =
+  | LegacyColor<Extract<RowPanelSpec, { kind: 'strip' }>>
+  | (Omit<Extract<RowPanelSpec, { kind: 'features' }>, 'encoding'> & {
+      encoding?: {
+        color?: LegacyColor<ColorChannel>
+        label?: string
+      }
+    })
+
+export function readRowPanel(panel: RowPanelSpec | LegacyRowPanel) {
+  if (panel.kind === 'strip') {
+    return readColor<Extract<RowPanelSpec, { kind: 'strip' }>>(panel)
+  }
+  const color = panel.encoding?.color
+  return (
+    color
+      ? { ...panel, encoding: { ...panel.encoding, color: readColor(color) } }
+      : panel
+  ) as RowPanelSpec
+}
+
+export type LegacyColumnTrack = ColumnTrackSpec & {
+  max?: number
+  colors?: Record<string, string>
+}
+
+/**
+ * Lifts a column track's `colors` onto `encoding.color` and its `max` onto
+ * `scales.y.domainMax`
+ */
+export function readColumnTrack(track: LegacyColumnTrack): ColumnTrackSpec {
+  const { max, colors, ...rest } = track
+  if (max === undefined && colors === undefined) {
+    return track
+  }
+  return {
+    ...(colors
+      ? {
+          encoding: {
+            color: {
+              domain: Object.keys(colors),
+              range: Object.values(colors),
+            },
+          },
+        }
+      : {}),
+    ...(max === undefined ? {} : { scales: { y: { domainMax: max } } }),
+    ...rest,
+  }
+}
+
+/**
+ * The color a color object gives each value listed, for a reader that keys
+ * colors by value, such as the residue letters of a scheme or a text track
+ */
+export function colorTable(spec: ColorSpec, values: Iterable<string>) {
+  return Object.fromEntries(
+    resolveScale(spec, values).legend.map(e => [e.id, e.color]),
+  )
+}
+
+/**
+ * The letter-to-color table an object `colorScheme` gives, `{domain, range}`
+ * or the earlier `{map}`
+ */
+export function letterColors(scheme: Exclude<ColorScheme, string>) {
+  return 'map' in scheme ? scheme.map : colorTable(scheme, scheme.domain ?? [])
+}

package/src/types.ts

@@ -1,4 +1,4 @@
-import type { ResolvedScale, ScaleSpec } from './scales.ts'
+import type { ColorChannel, ColorSpec, SharedScale } from './scales.ts'
 import type { Annotation } from 'msa-parsers'
 
 export interface Accession {
@@ -8,7 +8,7 @@ export interface Accession {
 }
 // every kind draws into the same per-column space; drawTracks.ts dispatches on
 // it to pick the draw function
-export type TrackKind = 'text' | 'bar' | 'logo' | 'arc' | 'ruler'
+export type TrackKind = 'text' | 'bar' | 'logo' | 'arc' | 'ruler' | 'reference'
 
 /**
  * Which channel the color scheme paints. `fill` colors the cell a residue sits
@@ -18,11 +18,17 @@ export type TrackKind = 'text' | 'bar' | 'logo' | 'arc' | 'ruler'
 export type ResidueEncoding = 'fill' | 'color'
 
 /**
- * The residue colors: a scheme name from the built-in table, or a scale's
- * `{map}` of letter to color, which leaves every letter it does not list
- * uncolored
+ * The residue colors: a scheme name from the built-in table, or a color object
+ * over residue letters, `{domain: ['K', 'R'], range: ['#1f77b4', '#1f77b4']}`,
+ * which leaves every letter it does not list uncolored
  */
-export type ColorScheme = string | Required<Pick<ScaleSpec, 'map'>>
+export type ColorScheme =
+  | string
+  | Pick<ColorSpec, 'domain' | 'range'>
+  | {
+      /** @deprecated the earlier spelling of `{domain, range}` */
+      map: Record<string, string>
+    }
 
 export interface BasicTrackModel {
   id: string
@@ -75,7 +81,8 @@ export interface ArcSpec {
 // a track supplied as data in the snapshot rather than computed from the
 // alignment. `values` (bar) or `data` (text) index alignment columns, or the
 // 1-based residues of `row` when it names one; `arcs` (arc) name two such
-// positions each
+// positions each. `scales.y.domainMax` is the bar value drawn at full height,
+// and a text track's `encoding.color` colors its characters
 export interface ColumnTrackSpec {
   id: string
   name: string
@@ -83,32 +90,29 @@ export interface ColumnTrackSpec {
   values?: number[]
   data?: string
   arcs?: ArcSpec[]
-  max?: number
   color?: string
-  colors?: Record<string, string>
+  encoding?: { color?: ColorSpec }
+  scales?: { y?: { domainMax?: number } }
   row?: string
   height?: number
 }
 
 /**
- * A strip panel: one cell per row, colored from a `rowData` field through
- * `scale`, which is ggtree's `gheatmap`. `width` is in pixels and defaults to
- * the row height, and `header` labels the column and defaults to the field.
- * `legend` titles the strip's legend and defaults to the field, and strips
- * naming one title share one legend.
+ * A strip panel: one cell per row, colored from a `rowData` field through the
+ * color object's members, which is ggtree's `gheatmap`. `width` is in pixels
+ * and defaults to the row height, and `header` labels the column and defaults
+ * to the field. Strips declaring the same members and `title` share one scale
+ * and one legend.
  */
-export interface RowStripSpec {
+export interface RowStripSpec extends ColorChannel {
   kind: 'strip'
-  field: string
-  scale?: ScaleSpec
   width?: number
   header?: string
-  legend?: string
 }
 
 /** the channels a `features` panel reads off the feature table */
 export interface FeatureEncodingSpec {
-  color?: { field: string; scale?: ScaleSpec }
+  color?: ColorChannel
   label?: string
 }
 
@@ -150,7 +154,8 @@ interface ResolvedPanelBase {
   width: number
   offsetX: number
   legend: LegendEntry[]
-  /** the legend this panel's entries go under; absent means the domain key */
+  /** the scale this panel's entries list under; absent means the domain key */
+  legendKey?: string
   legendTitle?: string
 }
 
@@ -497,17 +502,15 @@ export type EncodingChannel =
   | 'featureLabel'
 
 /**
- * A channel, the field feeding it, and the scale it reads that field through.
- * See docs/layers.md
+ * A channel, the field feeding it, and the color object's members it reads
+ * that field through. See docs/layers.md
  */
-export interface Encoding {
+export interface Encoding extends ColorChannel {
   channel: EncodingChannel
-  field: string
-  scale?: ScaleSpec
 }
 
 /** an Encoding with its scale resolved against the values in the table */
-export type ResolvedEncoding = Encoding & ResolvedScale
+export type ResolvedEncoding = Encoding & SharedScale
 
 /** a Highlight resolved to visible column indices and row indices */
 export interface ResolvedHighlight {

package/src/useDragScroll.ts

@@ -1,8 +1,9 @@
 import { useEffect, useRef, useState } from 'react'
 
 /**
- * Tracks a mouse drag along a single axis and reports the scroll delta on each
- * animation frame. Shared by the horizontal Minimap and the VerticalScrollbar.
+ * Tracks a pointer drag along a single axis and reports the scroll delta on
+ * each animation frame. Shared by the horizontal Minimap, the VerticalScrollbar
+ * and the dividers.
  *
  * `onScroll` is invoked with the pixel delta since drag start and the scroll
  * offset captured when the drag began. Memoize it (useCallback) so the document
@@ -21,7 +22,7 @@ export function useDragScroll(
   useEffect(() => {
     if (mouseDown !== undefined) {
       const { client: startClient, startScroll } = mouseDown
-      function onMove(event: MouseEvent) {
+      function onMove(event: PointerEvent) {
         if (!scheduled.current) {
           scheduled.current = true
           requestAnimationFrame(() => {
@@ -34,18 +35,20 @@ export function useDragScroll(
       function onUp() {
         setMouseDown(undefined)
       }
-      document.addEventListener('mousemove', onMove)
-      document.addEventListener('mouseup', onUp)
+      document.addEventListener('pointermove', onMove)
+      document.addEventListener('pointerup', onUp)
+      document.addEventListener('pointercancel', onUp)
       return () => {
-        document.removeEventListener('mousemove', onMove)
-        document.removeEventListener('mouseup', onUp)
+        document.removeEventListener('pointermove', onMove)
+        document.removeEventListener('pointerup', onUp)
+        document.removeEventListener('pointercancel', onUp)
       }
     }
   }, [axis, onScroll, mouseDown])
 
   return {
     dragging: mouseDown !== undefined,
-    startDrag: (event: React.MouseEvent, startScroll: number) => {
+    startDrag: (event: React.PointerEvent, startScroll: number) => {
       setMouseDown({
         client: axis === 'x' ? event.clientX : event.clientY,
         startScroll,