@jbrowse/product-core 4.3.0 → 5.0.0-beta.10

package/esm/Session/BaseSession.js

@@ -1,68 +1,436 @@
+import { readConfObject } from '@jbrowse/core/configuration';
+import SnackbarModel from '@jbrowse/core/ui/SnackbarModel';
+import { setNumberGrouping } from '@jbrowse/core/util';
+import { freezeDeep } from '@jbrowse/core/util/freezeDeep';
+import { isSameHighlight } from '@jbrowse/core/util/highlights';
+import { isFeature, unwrapFeature } from '@jbrowse/core/util/simpleFeature';
 import { ElementId } from '@jbrowse/core/util/types/mst';
-import { getParent, isStateTreeNode, types } from '@jbrowse/mobx-state-tree';
+import { cast, getParent, isStateTreeNode, types, } from '@jbrowse/mobx-state-tree';
+import { observable } from 'mobx';
+import { applyDeveloperMode } from './developerMode.js';
+function isAnimationMode(val) {
+    return val === 'system' || val === 'enabled' || val === 'disabled';
+}
+/**
+ * #stateModel BaseSessionModel
+ *
+ * base session shared by all JBrowse products. Be careful what you include
+ * here, everything will use it.
+ */
 export function BaseSessionModel(_pluginManager) {
-    return types
+    const baseModel = types
         .model({
+        /**
+         * #property
+         */
         id: ElementId,
+        /**
+         * #property
+         */
         name: types.string,
-        margin: 0,
+        /**
+         * #property
+         * used to keep track of which view is in focus
+         */
+        focusedViewId: types.maybe(types.string),
+        /**
+         * #property
+         * translucent bands over genomic regions; every view draws the ones on
+         * its own assemblies
+         */
+        highlights: types.stripDefault(types.array(types.frozen()), []),
+        /**
+         * #property
+         */
+        highlightsVisible: types.stripDefault(types.boolean, true),
+        /**
+         * #property
+         * whether a band's label is written on it
+         */
+        highlightLabelsVisible: types.stripDefault(types.boolean, true),
+        /**
+         * #property
+         * views, tracks, displays and widgets `pruneUnbuildableNodes` took out of
+         * the tree because this build has no plugin for their type, each with the
+         * anchor that puts it back. Nothing in the session reads its contents,
+         * and `pruneUnbuildableNodes` defines their structure.
+         *
+         * It is a **declared property** because MST drops undeclared snapshot
+         * keys without error. Without this declaration the held nodes survive
+         * the prune and are then discarded when `setSession` builds the tree,
+         * while every unit test of the prune still passes.
+         * `heldNodesSurviveTheSession.test.ts` tests that they survive.
+         */
+        heldForMissingPlugins: types.stripDefault(types.frozen(), undefined),
     })
         .volatile(() => ({
+        /**
+         * #volatile
+         * this is the globally "selected" object. can be anything. code that
+         * wants to deal with this should examine it to see what kind of thing it
+         * is.
+         */
+        // eslint-disable-next-line @typescript-eslint/no-unnecessary-type-assertion
         selection: undefined,
+        /**
+         * #volatile
+         * this is the globally "hovered" object. can be anything. code that
+         * wants to deal with this should examine it to see what kind of thing it
+         * is.
+         */
+        // eslint-disable-next-line @typescript-eslint/no-unnecessary-type-assertion
         hovered: undefined,
+        /**
+         * #volatile
+         */
+        queueOfDialogs: [],
+        /**
+         * #volatile
+         * runtime user-preference overrides keyed by preference id, resolved by
+         * `getPreference` against the `configuration.preferences` admin defaults.
+         * Empty here (config-only); products that let users edit preferences load
+         * and persist these via localStorage. A runtime override map layered over
+         * config defaults, kept off the snapshot since prefs are local UI.
+         *
+         * An `observable.map` (not a plain object reassigned wholesale) so each
+         * preference is its own tracked key: writing one (`setScrollZoom`) can't
+         * invalidate a reader of another. A single spread-replaced object made
+         * every setter wake every reader, so toggling scroll-to-zoom re-fetched
+         * every track.
+         *
+         * `deep: false` keeps an object-valued preference a plain object rather
+         * than a MobX Proxy, which V8's structured-clone serializer rejects. The
+         * map still notifies per key on `set`, so shallow values lose no
+         * reactivity — and nothing can mutate a preference in place, because
+         * `setPreferenceOverride` freezes what it stores.
+         */
+        preferencesOverrides: observable.map(undefined, {
+            deep: false,
+        }),
     }))
         .views(self => ({
+        /**
+         * #getter
+         */
         get root() {
             return getParent(self);
         },
     }))
         .views(self => ({
+        /**
+         * #getter
+         */
         get jbrowse() {
             return self.root.jbrowse;
         },
+        /**
+         * #getter
+         */
         get rpcManager() {
             return self.root.rpcManager;
         },
+        /**
+         * #getter
+         */
         get configuration() {
             return this.jbrowse.configuration;
         },
+        /**
+         * #getter
+         */
         get adminMode() {
             return self.root.adminMode;
         },
+        /**
+         * #getter
+         */
         get textSearchManager() {
             return self.root.textSearchManager;
         },
     }))
         .views(self => ({
+        /**
+         * #getter
+         */
         get assemblies() {
             return self.jbrowse.assemblies;
         },
+        /**
+         * #getter
+         */
+        get DialogComponent() {
+            return self.queueOfDialogs[0]?.[0];
+        },
+        /**
+         * #getter
+         */
+        get DialogProps() {
+            return self.queueOfDialogs[0]?.[1];
+        },
+    }))
+        .views(self => ({
+        /**
+         * #method
+         * the admin/embedder `configuration.preferences` value for a key, ignoring
+         * any runtime override — i.e. what a reset falls back to. Exposed rather
+         * than inlined because "differs from the default" is a question the
+         * Preferences reset diff asks about settings this map doesn't hold (see
+         * `defaultUseWorkspaces`).
+         */
+        getPreferenceDefault(key) {
+            const { preferences } = self.configuration;
+            return preferences ? readConfObject(preferences, key) : undefined;
+        },
+        /**
+         * #method
+         * resolved value of a user preference: a runtime override if the user set
+         * one, otherwise the admin/embedder `configuration.preferences` default.
+         * The override map is empty unless the product loads it (web/desktop).
+         */
+        getPreference(key) {
+            const override = self.preferencesOverrides.get(key);
+            return override === undefined
+                ? this.getPreferenceDefault(key)
+                : override;
+        },
+        /**
+         * #method
+         * every scalar preference override that currently differs from its
+         * config/admin default, as `{ path, from, to }` rows whose path is the
+         * override's own key. A scalar pref (animationMode, scrollZoom) whose
+         * override equals the default is omitted, since reverting it is a no-op.
+         */
+        getPreferenceChanges() {
+            const changes = [];
+            for (const [key, value] of self.preferencesOverrides.entries()) {
+                const dflt = this.getPreferenceDefault(key);
+                if (value !== dflt) {
+                    changes.push({
+                        path: [key],
+                        from: dflt,
+                        to: value,
+                    });
+                }
+            }
+            return changes;
+        },
+    }))
+        .views(self => ({
+        /**
+         * #getter
+         * resolved feature-layout animation mode (never undefined)
+         */
+        get animationMode() {
+            const mode = self.getPreference('animationMode');
+            return isAnimationMode(mode) ? mode : 'enabled';
+        },
+        /**
+         * #getter
+         * resolved scroll-to-zoom preference. Global and personal (never shared in
+         * a session snapshot); every wheel-zoom view reads this single value.
+         */
+        get scrollZoom() {
+            return self.getPreference('scrollZoom') === true;
+        },
+        /**
+         * #getter
+         * resolved thousand-separator preference. Read for display in the
+         * Preferences dialog; the formatter itself reads a plain module variable
+         * set at startup in each realm (see `setNumberGrouping`), because worker-
+         * built strings can't see a main-thread observable.
+         */
+        get numberGrouping() {
+            return self.getPreference('numberGrouping') !== false;
+        },
     }))
         .actions(self => ({
+        afterAttach() {
+            // push the admin/embedder default down to the formatter, which is a
+            // plain module variable rather than an observable (see
+            // `setNumberGrouping`). Embedded products stop here; web and desktop
+            // compose PreferencesSessionMixin, whose own afterAttach runs after
+            // this one and re-applies the value once the user's stored overrides
+            // are loaded, so a user override still wins over the config default.
+            setNumberGrouping(self.numberGrouping);
+        },
+        /**
+         * #action
+         * set the global selection, i.e. the globally-selected object. can be a
+         * feature, a view, just about anything
+         *
+         * A feature is unwrapped on the way in, so app state never holds a
+         * jexlFeatureProxy. `isFeature` accepts a proxy, but on one `id` is a
+         * data field rather than the method the Feature type promises — every
+         * consumer doing `isFeature(selection) ? selection.id() : …` would throw.
+         */
         setSelection(thing) {
-            self.selection = thing;
+            self.selection = isFeature(thing) ? unwrapFeature(thing) : thing;
         },
+        /**
+         * #action
+         * clears the global selection
+         */
         clearSelection() {
             self.selection = undefined;
         },
+        /**
+         * #action
+         */
         setHovered(thing) {
             self.hovered = thing;
         },
-    }))
-        .postProcessSnapshot(snap => {
-        if (!snap) {
-            return snap;
-        }
-        const { margin, ...rest } = snap;
-        return {
-            ...rest,
-            ...(margin ? { margin } : {}),
-        };
-    });
+        /**
+         * #action
+         */
+        setHighlightsVisible(arg) {
+            self.highlightsVisible = arg;
+        },
+        /**
+         * #action
+         */
+        setHighlightLabelsVisible(arg) {
+            self.highlightLabelsVisible = arg;
+        },
+        /**
+         * #action
+         * an identical entry is not added twice, so a spec launched again does not
+         * stack its bands. Adding shows the bands again, since a highlight made
+         * while they are off would otherwise read as nothing happening
+         */
+        addHighlight(highlight) {
+            if (!self.highlights.some(h => isSameHighlight(h, highlight))) {
+                self.highlights.push(highlight);
+            }
+            self.highlightsVisible = true;
+        },
+        /**
+         * #action
+         */
+        removeHighlight(highlight) {
+            self.highlights.remove(highlight);
+        },
+        /**
+         * #action
+         */
+        updateHighlight(old, updates) {
+            const idx = self.highlights.indexOf(old);
+            if (idx !== -1) {
+                self.highlights[idx] = { ...old, ...updates };
+                self.highlightsVisible = true;
+            }
+        },
+        /**
+         * #action
+         */
+        setHighlights(highlights) {
+            self.highlights = cast(highlights);
+            if (highlights.length) {
+                self.highlightsVisible = true;
+            }
+        },
+        /**
+         * #action
+         * set a runtime user-preference override (see `getPreference`). Mutates
+         * volatile state; products persist these to localStorage. An `undefined`
+         * value deletes the key (rather than leaving a phantom entry that
+         * `getPreference` reads as absent) so the store never holds dead keys.
+         */
+        setPreferenceOverride(key, value) {
+            if (value === undefined) {
+                self.preferencesOverrides.delete(key);
+            }
+            else {
+                // frozen because `deep: false` hands an object-valued preference
+                // straight back out by reference, so the "nothing mutates a
+                // preference in place" this store relies on is enforced rather than
+                // assumed
+                self.preferencesOverrides.set(key, freezeDeep(value));
+            }
+        },
+        /**
+         * #action
+         * clear every runtime preference override at once, so each falls back to
+         * its config/admin default. Backs the Preferences dialog "Reset to
+         * defaults" button.
+         */
+        clearPreferenceOverrides() {
+            self.preferencesOverrides.clear();
+        },
+        /**
+         * #action
+         * clear a single runtime preference override (see `getPreference`) so it
+         * falls back to its config/admin default. Backs the per-entry reset in the
+         * Preferences dialog "Reset to defaults" confirmation.
+         */
+        clearPreferenceOverride(key) {
+            self.preferencesOverrides.delete(key);
+        },
+        /**
+         * #action
+         * set the global scroll-to-zoom preference (see the `scrollZoom` getter)
+         */
+        setScrollZoom(flag) {
+            this.setPreferenceOverride('scrollZoom', flag);
+        },
+        /**
+         * #action
+         */
+        setName(str) {
+            self.name = str;
+        },
+        /**
+         * #action
+         * `undefined` is "no view is focused", which the property has always been
+         * able to hold (`types.maybe`) and this had no way to spell. Nothing
+         * cleared it on teardown as a result: a view that was focused when it left
+         * the session left its id behind, and since every consumer compares
+         * `focusedViewId === view.id`, the id matched nothing, the focus ring
+         * vanished with nothing to say why, and the dead id persisted into a saved
+         * or shared session. `takeOut` clears it now.
+         */
+        setFocusedViewId(viewId) {
+            self.focusedViewId = viewId;
+        },
+        /**
+         * #action
+         */
+        removeActiveDialog() {
+            self.queueOfDialogs = self.queueOfDialogs.slice(1);
+        },
+        /**
+         * #action
+         */
+        queueDialog(doneCallback) {
+            // its own entry, not the head: a late second call must not close the
+            // dialog queued behind it
+            const entry = doneCallback(() => {
+                this.removeDialog(entry);
+            });
+            self.queueOfDialogs = [...self.queueOfDialogs, entry];
+        },
+        /**
+         * #action
+         */
+        removeDialog(entry) {
+            self.queueOfDialogs = self.queueOfDialogs.filter(d => d !== entry);
+        },
+    }));
+    return types.compose(baseModel, SnackbarModel()).actions(self => ({
+        // after the compose rather than in the afterAttach above, because the
+        // notices land in the snackbar this line is the first place to hold both
+        // halves of. Web and desktop reach it a second time once the user's stored
+        // overrides are loaded (`PreferencesSessionMixin`), and our MST fork
+        // auto-chains both hooks.
+        afterAttach() {
+            applyDeveloperMode(self);
+        },
+    }));
 }
+/** Type guard for BaseSession */
 export function isBaseSession(thing) {
     return 'id' in thing && 'name' in thing && 'root' in thing;
 }
+/** Type guard for whether a thing is JBrowse session */
 export function isSession(thing) {
     return isStateTreeNode(thing) && isBaseSession(thing);
 }

package/esm/Session/Connections.d.ts

@@ -1,21 +1,128 @@
 import type PluginManager from '@jbrowse/core/PluginManager';
-import type { AnyConfigurationModel } from '@jbrowse/core/configuration';
+import type { AnyConfiguration, AnyConfigurationModel } from '@jbrowse/core/configuration';
 import type { BaseConnectionConfigModel } from '@jbrowse/core/pluggableElementTypes/models/baseConnectionConfig';
 import type { IAnyStateTreeNode, Instance } from '@jbrowse/mobx-state-tree';
+/**
+ * Persisted config of a connection track the user has opened. Keyed by trackId
+ * in `connectionTrackConfigs`. `connectionId` records provenance so the track
+ * can be grouped under its connection and re-hydrated on demand.
+ */
+export interface ConnectionTrackConfigEntry {
+    connectionId: string;
+    config: Record<string, unknown>;
+}
+/**
+ * #stateModel ConnectionManagementSessionMixin
+ */
 export declare function ConnectionManagementSessionMixin(pluginManager: PluginManager): import("@jbrowse/mobx-state-tree").IModelType<{
-    connectionInstances: import("@jbrowse/mobx-state-tree").IArrayType<import("@jbrowse/mobx-state-tree").IAnyType>;
+    /**
+     * #property
+     */
+    connectionInstances: import("@jbrowse/mobx-state-tree").IOptionalIType<import("@jbrowse/mobx-state-tree").IArrayType<import("@jbrowse/mobx-state-tree").IAnyType>, [undefined]>;
+    /**
+     * #property
+     * Persisted configs of connection tracks the user has opened, keyed by
+     * trackId. Unlike `connectionInstances` (stripped from snapshots, holds
+     * the whole fetched hub), this holds only the tracks in use, so an open
+     * connection track resolves synchronously on session load without
+     * re-establishing the connection.
+     */
+    connectionTrackConfigs: import("@jbrowse/mobx-state-tree").IOptionalIType<import("@jbrowse/mobx-state-tree").IType<Record<string, ConnectionTrackConfigEntry>, Record<string, ConnectionTrackConfigEntry>, Record<string, ConnectionTrackConfigEntry>>, [undefined]>;
 }, {
+    /**
+     * #getter
+     */
     readonly connections: BaseConnectionConfigModel[];
 } & {
-    makeConnection(configuration: AnyConfigurationModel, initialSnapshot?: {}): any;
-    prepareToBreakConnection(configuration: AnyConfigurationModel): [() => void, Record<string, number>] | undefined;
+    /**
+     * #action
+     */
+    makeConnection(configuration: AnyConfigurationModel, initialSnapshot?: object): any;
+    /**
+     * #action
+     * Remove a live connection instance. Tolerant of an already-dormant
+     * connection (its instance is stripped from the session on reload).
+     * Leaves persisted open-track configs alone — the connect() error path
+     * calls this and the user's already-open tracks must survive a transient
+     * failure. Full removal goes through `deleteConnection`.
+     */
     breakConnection(configuration: AnyConfigurationModel): void;
+    /**
+     * #action
+     * Close every track a connection contributed — the live instance's
+     * tracks plus any persisted open-track configs (a dormant connection,
+     * never expanded this session, still renders its opened tracks from
+     * `connectionTrackConfigs`) — from all views/widgets, drop the live
+     * instance, and drop the persisted configs. The session is left as if the
+     * connection had never loaded.
+     */
+    teardownConnection(configuration: AnyConfigurationModel): void;
+    /**
+     * #action
+     * Fully remove a connection: tear down its tracks and live instance, then
+     * delete its config.
+     */
     deleteConnection(configuration: AnyConfigurationModel): any;
-    addConnectionConf(connectionConf: AnyConfigurationModel): any;
+    /**
+     * #action
+     * Adds to the **config**, not the session: `jbrowse.connections`, which
+     * every visitor to this instance loads. jbrowse-web overrides this so a
+     * non-admin's connection lands in `sessionConnections` instead — see
+     * WebSessionConnectionsMixin, whose `addSessionConnectionConf` is what
+     * to call when you mean the session specifically rather than "wherever
+     * this user's edits go".
+     *
+     * Applications without that override (Desktop, the embedded products)
+     * have only this one destination, and it is the right one there: their
+     * config and session are saved as a single document.
+     */
+    addConnectionConf(connectionConf: AnyConfiguration): any;
+    /**
+     * #action
+     */
     clearConnections(): void;
-}, import("@jbrowse/mobx-state-tree")._NotCustomized, import("@jbrowse/mobx-state-tree").ModelSnapshotType<{
-    connectionInstances: import("@jbrowse/mobx-state-tree").IArrayType<import("@jbrowse/mobx-state-tree").IAnyType>;
-}>>;
+    /**
+     * #action
+     * Snapshot a just-opened connection track's config into
+     * `connectionTrackConfigs` so it survives session reload. No-op if the
+     * track isn't connection-provided or is already captured (edits go
+     * through `updateConnectionTrackConfig`).
+     */
+    captureConnectionTrack(trackId: string): void;
+    /**
+     * #action
+     * Persist an edit to an opened connection track. The full config is
+     * stored (not a delta): the connection's fetched "base" isn't present at
+     * load, so only a complete config resolves synchronously.
+     */
+    updateConnectionTrackConfig(trackConf: Record<string, unknown> & {
+        trackId: string;
+    }): void;
+    /**
+     * #action
+     * Upsert one opened connection track's persisted config.
+     */
+    setConnectionTrackConfig(trackId: string, connectionId: string, config: Record<string, unknown>): void;
+    /**
+     * #action
+     * Drop a connection track's persisted config once no open view still
+     * references it, so the session doesn't accumulate closed tracks.
+     */
+    pruneConnectionTrackConfig(trackId: string): void;
+    /**
+     * #action
+     * Lazily establish a single connection by id if it isn't already live;
+     * the track selector calls it when the connection's category is
+     * expanded. Fetches without launching a view or showing a success
+     * snackbar; already-open tracks keep
+     * rendering from `connectionTrackConfigs` meanwhile. Idempotent.
+     */
+    hydrateConnection(connectionId: string): void;
+}, import("@jbrowse/mobx-state-tree")._NotCustomized, import("@jbrowse/mobx-state-tree")._NotCustomized>;
+/** Session mixin MST type for a session that has connections */
 export type SessionWithConnectionsType = ReturnType<typeof ConnectionManagementSessionMixin>;
+/** Instance of a session that has connections: `connectionInstances`,
+ * `makeConnection()`, etc. */
 export type SessionWithConnections = Instance<SessionWithConnectionsType>;
+/** Type guard for SessionWithConnections */
 export declare function isSessionWithConnections(session: IAnyStateTreeNode): session is SessionWithConnections;