jbrowse-plugin-msaview 3.1.0 → 3.2.0

package/src/LaunchMsaViewExtensionPoint/index.ts

@@ -1,4 +1,7 @@
+import { launchMsaView } from '../utils/launchMsaView'
+
 import type { OrthologParams } from '../MsaViewPanel/model'
+import type { MsaViewPlacement } from '../utils/workspaces'
 import type PluginManager from '@jbrowse/core/PluginManager'
 import type { AbstractSessionModel } from '@jbrowse/core/util'
 
@@ -39,6 +42,23 @@ interface LaunchMsaViewArgs {
    * snapshot property passes through the same way.
    */
   allowedGappyness?: number
+  /**
+   * Where the view lands: `stack` (default), `splitRight` or `newTab`. The
+   * declarative half of the launch — a link states the arrangement it wants
+   * instead of the reader dragging the view into place.
+   *
+   * The default is `stack` and has to stay `stack`: it is what every link
+   * written before this key existed already does, and the only thing an
+   * embedded session can do. The launch DIALOG defaults to `splitRight`
+   * instead (see `DEFAULT_LAUNCH_PLACEMENT`), because a launch from a gene
+   * feature is a connected pair and reads as a split.
+   *
+   * A spec that arranges more than these two views should use the host's own
+   * `layout` key instead, which states the whole tree and is applied after
+   * every view in the spec has launched. Both may be given; `layout` wins,
+   * being the later and more specific statement.
+   */
+  placement?: MsaViewPlacement
 }
 
 export default function LaunchMsaViewExtensionPointF(
@@ -76,8 +96,7 @@ export default function LaunchMsaViewExtensionPointF(
       // directly, and so is orthologParams (the model's own autorun picks it up).
       // Only sources needing launch-time resolution go through `init`: msaUrl
       // (AlphaFold sniff) and the name-indexed bgzip block (no native loader).
-      session.addView('MsaView', {
-        type: 'MsaView',
+      launchMsaView(session, {
         ...rest,
         data,
         ...(treeFileLocation

package/src/index.ts

@@ -9,6 +9,7 @@ import BgzipFastaMsaAdapterF from './BgzipFastaMsaAdapter'
 import LaunchMsaViewF from './LaunchMsaView'
 import LaunchMsaViewExtensionPointF from './LaunchMsaViewExtensionPoint'
 import MsaViewF from './MsaViewPanel'
+import { launchMsaView } from './utils/launchMsaView'
 import { version } from './version'
 
 import type PluginManager from '@jbrowse/core/PluginManager'
@@ -32,7 +33,9 @@ export default class MsaViewPlugin extends Plugin {
         label: 'Multiple sequence alignment view',
         icon: GridOn,
         onClick: (session: AbstractSessionModel) => {
-          session.addView('MsaView', {})
+          // stacked, by default: nothing was launched from, so there is no
+          // connected view for it to sit beside
+          launchMsaView(session, {})
         },
       })
     }

package/src/utils/launchMsaView.ts

@@ -0,0 +1,30 @@
+import { placeMsaView } from './workspaces'
+
+import type { MsaViewPlacement } from './workspaces'
+import type { AbstractSessionModel } from '@jbrowse/core/util'
+
+/**
+ * A launch, stated: what the view is, and where it goes. Everything but
+ * `placement` is a react-msaview or plugin-model snapshot property, passed
+ * through untouched so this never becomes a list that has to grow.
+ */
+export interface MsaViewLaunchSpec extends Record<string, unknown> {
+  /** default `stack`, the only thing an embedded session can do */
+  placement?: MsaViewPlacement
+}
+
+/**
+ * The one place a launch adds an MSA view -- the dialog's four tabs, the Add
+ * menu, and the `LaunchView-MsaView` extension point a session spec arrives on
+ * all come through here. Each of them used to run its own `addView` and none
+ * placed the result, which is how a launch from a gene feature landed stacked
+ * under the very genome view it was connected to.
+ */
+export function launchMsaView(
+  session: AbstractSessionModel,
+  { placement = 'stack', ...snapshot }: MsaViewLaunchSpec,
+) {
+  const view = session.addView('MsaView', { type: 'MsaView', ...snapshot })
+  placeMsaView(session, view.id, placement)
+  return view
+}

package/src/utils/workspaces.test.ts

@@ -0,0 +1,132 @@
+import { afterEach, beforeEach, expect, test, vi } from 'vitest'
+
+import { launchMsaView } from './launchMsaView'
+import {
+  DEFAULT_LAUNCH_PLACEMENT,
+  LAUNCH_PLACEMENT_KEY,
+  placeMsaView,
+  readLaunchPlacement,
+  resetWorkspacesWarning,
+  sessionSupportsPlacement,
+  writeLaunchPlacement,
+} from './workspaces'
+
+import type { AbstractSessionModel } from '@jbrowse/core/util'
+
+interface Recorded {
+  moves: unknown[]
+  workspaces: boolean[]
+  added: { type: string; snapshot: Record<string, unknown> }[]
+}
+
+function makeSession({
+  canPlace = true,
+  canEnable = true,
+}: { canPlace?: boolean; canEnable?: boolean } = {}) {
+  const recorded: Recorded = { moves: [], workspaces: [], added: [] }
+  const session: Record<string, unknown> = {
+    addView(type: string, snapshot: Record<string, unknown>) {
+      recorded.added.push({ type, snapshot })
+      return { id: `view-${recorded.added.length}` }
+    },
+  }
+  if (canPlace) {
+    session.setPendingMove = (move: unknown) => recorded.moves.push(move)
+  }
+  if (canEnable) {
+    session.setUseWorkspaces = (on: boolean) => recorded.workspaces.push(on)
+  }
+  return { session: session as unknown as AbstractSessionModel, recorded }
+}
+
+// node has no localStorage, and the plugin runs in a browser -- a Map-backed
+// stub keeps read/write round-tripping without pulling in jsdom
+function stubStorage() {
+  const store = new Map<string, string>()
+  vi.stubGlobal('localStorage', {
+    getItem: (key: string) => store.get(key) ?? null,
+    setItem: (key: string, value: string) => store.set(key, value),
+  })
+}
+
+beforeEach(() => {
+  resetWorkspacesWarning()
+  stubStorage()
+})
+
+afterEach(() => {
+  vi.restoreAllMocks()
+  vi.unstubAllGlobals()
+})
+
+test('stack places nothing, on a host that could tile', () => {
+  const { session, recorded } = makeSession()
+  placeMsaView(session, 'view-1', 'stack')
+  expect(recorded.moves).toEqual([])
+  expect(recorded.workspaces).toEqual([])
+})
+
+test('splitRight asks for the move, then turns workspaces on', () => {
+  const { session, recorded } = makeSession()
+  placeMsaView(session, 'view-1', 'splitRight')
+  expect(recorded.moves).toEqual([{ type: 'splitRight', viewId: 'view-1' }])
+  expect(recorded.workspaces).toEqual([true])
+})
+
+test('newTab is the same path with the other move type', () => {
+  const { session, recorded } = makeSession()
+  placeMsaView(session, 'view-1', 'newTab')
+  expect(recorded.moves).toEqual([{ type: 'newTab', viewId: 'view-1' }])
+})
+
+// an embedded session has no workspaces at all, so there is nothing to report
+test('a session with neither action is a silent no-op', () => {
+  const warn = vi.spyOn(console, 'warn').mockImplementation(() => {})
+  const { session, recorded } = makeSession({
+    canPlace: false,
+    canEnable: false,
+  })
+  placeMsaView(session, 'view-1', 'splitRight')
+  expect(recorded.moves).toEqual([])
+  expect(warn).not.toHaveBeenCalled()
+  expect(sessionSupportsPlacement(session)).toBe(false)
+})
+
+// the shape that broke jbrowse-plugin-protein3d silently: workspaces are there,
+// the action this plugin reaches for is not
+test('a half-supported host warns once and stacks', () => {
+  const warn = vi.spyOn(console, 'warn').mockImplementation(() => {})
+  const { session, recorded } = makeSession({ canPlace: false })
+  placeMsaView(session, 'view-1', 'splitRight')
+  placeMsaView(session, 'view-2', 'splitRight')
+  expect(recorded.moves).toEqual([])
+  expect(warn).toHaveBeenCalledTimes(1)
+  expect(warn.mock.calls[0]?.[0]).toContain('setPendingMove')
+})
+
+test('the dialog default is side-by-side, and a junk value falls back to it', () => {
+  expect(DEFAULT_LAUNCH_PLACEMENT).toBe('splitRight')
+  expect(readLaunchPlacement()).toBe('splitRight')
+  localStorage.setItem(LAUNCH_PLACEMENT_KEY, 'sideways')
+  expect(readLaunchPlacement()).toBe('splitRight')
+  writeLaunchPlacement('stack')
+  expect(readLaunchPlacement()).toBe('stack')
+})
+
+test('launchMsaView defaults to stack, so a spec written before placement existed is unchanged', () => {
+  const { session, recorded } = makeSession()
+  launchMsaView(session, { data: { msa: '>a\nAC' } })
+  expect(recorded.added).toEqual([
+    { type: 'MsaView', snapshot: { type: 'MsaView', data: { msa: '>a\nAC' } } },
+  ])
+  expect(recorded.moves).toEqual([])
+})
+
+// placement is a launch instruction, not view state: MST would drop it from the
+// snapshot without a word, and the view would land stacked with nothing said
+test('launchMsaView keeps placement out of the view snapshot', () => {
+  const { session, recorded } = makeSession()
+  launchMsaView(session, { placement: 'splitRight', colWidth: 10 })
+  expect(recorded.added[0]?.snapshot).toEqual({ type: 'MsaView', colWidth: 10 })
+  expect(recorded.moves).toEqual([{ type: 'splitRight', viewId: 'view-1' }])
+})

package/src/utils/workspaces.ts

@@ -0,0 +1,146 @@
+import type { AbstractSessionModel } from '@jbrowse/core/util'
+
+/**
+ * Where a launched MSA view lands. Every launch names one of these and stops
+ * there, so a host that arranges views differently is one function to teach.
+ *
+ *   stack       append below whatever is on screen
+ *   splitRight  its own cell to the right, beside the view it is connected to
+ *   newTab      its own tab in the current cell
+ */
+export type MsaViewPlacement = 'stack' | 'splitRight' | 'newTab'
+
+const PLACEMENTS: MsaViewPlacement[] = ['stack', 'splitRight', 'newTab']
+
+/**
+ * What the dialog does unasked. Side-by-side, because a launch from a gene
+ * feature sets `connectedViewId`: the pair shares a hover and a highlight, and
+ * reads as a split. A session spec defaults to `stack` instead.
+ */
+export const DEFAULT_LAUNCH_PLACEMENT: MsaViewPlacement = 'splitRight'
+
+export const LAUNCH_PLACEMENT_KEY = 'msaView-launchPlacement'
+
+/**
+ * The session actions that place a view in a tiled workspace. Only jbrowse-web
+ * and desktop have them, so feature-detect rather than import.
+ */
+interface SessionWithWorkspaces {
+  setUseWorkspaces: (useWorkspaces: boolean) => void
+  setPendingMove: (move: {
+    type: 'newTab' | 'splitRight'
+    viewId: string
+  }) => void
+}
+
+function hasAction(session: AbstractSessionModel, name: string) {
+  return (
+    name in session &&
+    typeof (session as unknown as Record<string, unknown>)[name] === 'function'
+  )
+}
+
+// Warned at most once. This is a property of the host, so the answer is the
+// same on every launch and a dialog the user reopens should not stack up noise.
+let warnedPartial = false
+
+export function resetWorkspacesWarning() {
+  warnedPartial = false
+}
+
+/**
+ * Whether this host can honor anything other than `stack`. Silent: the dialog
+ * asks on every render, and only a launch is worth warning about.
+ */
+export function sessionSupportsPlacement(session: AbstractSessionModel) {
+  return (
+    hasAction(session, 'setUseWorkspaces') &&
+    hasAction(session, 'setPendingMove')
+  )
+}
+
+function isSessionWithWorkspaces(
+  session: AbstractSessionModel,
+): session is AbstractSessionModel & SessionWithWorkspaces {
+  const canEnable = hasAction(session, 'setUseWorkspaces')
+  const canPlace = hasAction(session, 'setPendingMove')
+
+  // Missing BOTH is an embedded session: it has no workspaces, there is nothing
+  // to ask for, and silence is the right answer.
+  //
+  // Missing ONE is a host that has workspaces but places views some other way,
+  // and silence there is how the same feature broke in jbrowse-plugin-protein3d
+  // — jbrowse-web folded `setPendingMove` into its layout `init`, the guard went
+  // false, and the plugin simply stopped asking: no error, no missing feature,
+  // two views quietly stacking, nobody noticed for weeks. Feature detection
+  // cannot ask a host to announce a change, but it can tell "not supported here"
+  // from "supported, and gone".
+  //
+  // Two very different hosts produce this one shape and nothing on the session
+  // tells them apart, so the message carries both rather than a guess:
+  //
+  // - releases through v4.3.0, where placement is `setPendingMoveToSplitRight`,
+  //   a module function in @jbrowse/app-core rather than a session action.
+  //   Nothing is wrong and nothing needs fixing
+  // - a newer host that moved the action out from under us, which is the
+  //   regression this warning exists to catch
+  //
+  // Do not quiet the first case by sniffing the version. The alarm is only worth
+  // having if it fires on a shape it cannot explain, and these two are identical.
+  if (canEnable !== canPlace && !warnedPartial) {
+    warnedPartial = true
+    console.warn(
+      `jbrowse-plugin-msaview: this session supports workspaces but not ` +
+        `${canPlace ? 'setUseWorkspaces' : 'setPendingMove'}, so the MSA view ` +
+        `was stacked instead of tiled. Expected on releases through v4.3.0, ` +
+        `which place views through @jbrowse/app-core instead; on a newer host ` +
+        `it means the session API moved and the plugin needs updating to match.`,
+    )
+  }
+  return canEnable && canPlace
+}
+
+/**
+ * Put a freshly added view where the launch said to. `stack` is a placement
+ * rather than the absence of one, so no caller has to ask what host it is on.
+ */
+export function placeMsaView(
+  session: AbstractSessionModel,
+  viewId: string,
+  placement: MsaViewPlacement,
+) {
+  if (placement === 'stack' || !isSessionWithWorkspaces(session)) {
+    return
+  }
+  session.setPendingMove({ type: placement, viewId })
+  // Session-scoped: turning workspaces on for this session leaves the user's
+  // own default alone, which is what `setUseWorkspaces` (as against
+  // `setUseWorkspacesPreference`) is for.
+  session.setUseWorkspaces(true)
+}
+
+function isPlacement(value: unknown): value is MsaViewPlacement {
+  return PLACEMENTS.includes(value as MsaViewPlacement)
+}
+
+/**
+ * The dialog's own remembered choice — not the host's preferences system, which
+ * records whether the user likes workspaces and does not exist everywhere.
+ */
+export function readLaunchPlacement(): MsaViewPlacement {
+  try {
+    const stored = globalThis.localStorage.getItem(LAUNCH_PLACEMENT_KEY)
+    return isPlacement(stored) ? stored : DEFAULT_LAUNCH_PLACEMENT
+  } catch (error) {
+    console.error(error)
+    return DEFAULT_LAUNCH_PLACEMENT
+  }
+}
+
+export function writeLaunchPlacement(placement: MsaViewPlacement) {
+  try {
+    globalThis.localStorage.setItem(LAUNCH_PLACEMENT_KEY, placement)
+  } catch (error) {
+    console.error(error)
+  }
+}

package/src/version.ts

@@ -1 +1 @@
-export const version = '3.1.0'
+export const version = '3.2.0'