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

package/esm/Session/Connections.js

@@ -1,90 +1,212 @@
-import { readConfObject } from '@jbrowse/core/configuration';
-import { types } from '@jbrowse/mobx-state-tree';
-import { isBaseSession } from "./BaseSession.js";
+import { getSnapshot, types } from '@jbrowse/mobx-state-tree';
+import { asSession } from '../siblingCast.js';
+import { isBaseSession } from './BaseSession.js';
+/**
+ * #stateModel ConnectionManagementSessionMixin
+ */
 export function ConnectionManagementSessionMixin(pluginManager) {
     return types
         .model({
-        connectionInstances: types.array(pluginManager.pluggableMstType('connection', 'stateModel')),
+        /**
+         * #property
+         */
+        connectionInstances: types.stripDefault(types.array(pluginManager.pluggableMstType('connection', 'stateModel')), []),
+        /**
+         * #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: types.stripDefault(types.frozen(), {}),
     })
         .views(self => ({
+        /**
+         * #getter
+         */
         get connections() {
-            const { jbrowse } = self;
+            const { jbrowse } = asSession(self);
             return jbrowse.connections;
         },
     }))
-        .actions(self => ({
-        makeConnection(configuration, initialSnapshot = {}) {
-            const type = configuration.type;
-            if (!type) {
-                throw new Error('track configuration has no `type` listed');
-            }
-            const name = readConfObject(configuration, 'name');
-            const connectionType = pluginManager.getConnectionType(type);
-            if (!connectionType) {
-                throw new Error(`unknown connection type ${type}`);
-            }
-            const length = self.connectionInstances.push({
-                ...initialSnapshot,
-                name,
-                type,
-                configuration,
-            });
-            return self.connectionInstances[length - 1];
-        },
-        prepareToBreakConnection(configuration) {
-            const root = self;
-            const callbacksToDeref = [];
-            const derefTypeCount = {};
-            const name = readConfObject(configuration, 'name');
-            const connection = self.connectionInstances.find(c => c.name === name);
-            if (!connection) {
-                return undefined;
-            }
-            for (const track of connection.tracks) {
-                const ref = root.getReferring(track);
-                root.removeReferring(ref, track, callbacksToDeref, derefTypeCount);
-            }
-            return [
-                () => {
-                    for (const cb of callbacksToDeref) {
-                        cb();
-                    }
-                    this.breakConnection(configuration);
-                },
-                derefTypeCount,
-            ];
-        },
-        breakConnection(configuration) {
-            const name = readConfObject(configuration, 'name');
-            const connection = self.connectionInstances.find(c => c.name === name);
-            if (!connection) {
-                throw new Error(`no connection found with name ${name}`);
-            }
-            self.connectionInstances.remove(connection);
-        },
-        deleteConnection(configuration) {
-            const { jbrowse } = self;
-            return jbrowse.deleteConnectionConf(configuration);
-        },
-        addConnectionConf(connectionConf) {
-            const { jbrowse } = self;
-            return jbrowse.addConnectionConf(connectionConf);
-        },
-        clearConnections() {
-            self.connectionInstances.clear();
-        },
-    }))
-        .postProcessSnapshot(snap => {
-        if (!snap) {
-            return snap;
-        }
-        const { connectionInstances, ...rest } = snap;
+        .actions(self => {
+        // this mixin is always composed onto a base session with a jbrowse config
+        // and reference-management helpers; alias once instead of re-casting self
+        const session = self;
         return {
-            ...rest,
-            ...(connectionInstances?.length ? { connectionInstances } : {}),
+            /**
+             * #action
+             */
+            makeConnection(configuration, initialSnapshot = {}) {
+                const { type, connectionId } = configuration;
+                if (!type) {
+                    throw new Error('connection configuration has no `type` listed');
+                }
+                const existing = self.connectionInstances.find(c => c.connectionId === connectionId);
+                if (existing) {
+                    return existing;
+                }
+                else {
+                    const length = self.connectionInstances.push({
+                        ...initialSnapshot,
+                        type,
+                        configuration,
+                    });
+                    return self.connectionInstances[length - 1];
+                }
+            },
+            /**
+             * #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) {
+                const { connectionId } = configuration;
+                const connection = self.connectionInstances.find(c => c.connectionId === connectionId);
+                if (connection) {
+                    self.connectionInstances.remove(connection);
+                }
+            },
+            /**
+             * #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) {
+                const { connectionId } = configuration;
+                const connection = self.connectionInstances.find(c => c.connectionId === connectionId);
+                const trackIds = [
+                    ...new Set([
+                        ...(connection?.tracks.map((t) => t.trackId) ?? []),
+                        ...Object.entries(self.connectionTrackConfigs)
+                            .filter(([, e]) => e.connectionId === connectionId)
+                            .map(([trackId]) => trackId),
+                    ]),
+                ];
+                const referring = session.getReferringMultiple(trackIds);
+                for (const trackId of trackIds) {
+                    session.dereferenceTrack(trackId, referring.get(trackId) ?? []);
+                }
+                this.breakConnection(configuration);
+                // closing the tracks above prunes their configs via hideTrack; this
+                // mops up any orphaned entry that had no open view
+                const remaining = Object.fromEntries(Object.entries(self.connectionTrackConfigs).filter(([, e]) => e.connectionId !== connectionId));
+                if (Object.keys(remaining).length !==
+                    Object.keys(self.connectionTrackConfigs).length) {
+                    self.connectionTrackConfigs = remaining;
+                }
+            },
+            /**
+             * #action
+             * Fully remove a connection: tear down its tracks and live instance, then
+             * delete its config.
+             */
+            deleteConnection(configuration) {
+                this.teardownConnection(configuration);
+                return session.jbrowse.deleteConnectionConf(configuration);
+            },
+            /**
+             * #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) {
+                return session.jbrowse.addConnectionConf(connectionConf);
+            },
+            /**
+             * #action
+             */
+            clearConnections() {
+                self.connectionInstances.clear();
+            },
+            /**
+             * #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) {
+                if (!(trackId in self.connectionTrackConfigs)) {
+                    for (const conn of self.connectionInstances) {
+                        const track = conn.tracks.find((t) => t.trackId === trackId);
+                        if (track) {
+                            this.setConnectionTrackConfig(trackId, conn.connectionId, structuredClone(getSnapshot(track)));
+                            break;
+                        }
+                    }
+                }
+            },
+            /**
+             * #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) {
+                const existing = self.connectionTrackConfigs[trackConf.trackId];
+                if (existing) {
+                    this.setConnectionTrackConfig(trackConf.trackId, existing.connectionId, trackConf);
+                }
+            },
+            /**
+             * #action
+             * Upsert one opened connection track's persisted config.
+             */
+            setConnectionTrackConfig(trackId, connectionId, config) {
+                self.connectionTrackConfigs = {
+                    ...self.connectionTrackConfigs,
+                    [trackId]: { connectionId, config },
+                };
+            },
+            /**
+             * #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) {
+                if (trackId in self.connectionTrackConfigs &&
+                    session.getReferring(trackId).length === 0) {
+                    const { [trackId]: _removed, ...rest } = self.connectionTrackConfigs;
+                    self.connectionTrackConfigs = rest;
+                }
+            },
+            /**
+             * #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) {
+                // makeConnection is idempotent (returns the existing live instance if
+                // one matches), so no separate liveness check is needed
+                const conf = self.connections.find(c => c.connectionId === connectionId);
+                if (conf) {
+                    this.makeConnection(conf, { silent: true });
+                }
+            },
         };
     });
 }
+/** Type guard for SessionWithConnections */
 export function isSessionWithConnections(session) {
     return isBaseSession(session) && 'connectionInstances' in session;
 }

package/esm/Session/DrawerWidgets.d.ts

@@ -1,36 +1,168 @@
 import type PluginManager from '@jbrowse/core/PluginManager';
 import type { AnyConfigurationModel } from '@jbrowse/core/configuration';
+import type { DrawerPosition, Widget } from '@jbrowse/core/util/types';
 import type { IAnyStateTreeNode, Instance } from '@jbrowse/mobx-state-tree';
+/**
+ * #stateModel DrawerWidgetSessionMixin
+ */
 export declare function DrawerWidgetSessionMixin(pluginManager: PluginManager): import("@jbrowse/mobx-state-tree").IModelType<{
-    drawerPosition: import("@jbrowse/mobx-state-tree").IOptionalIType<import("@jbrowse/mobx-state-tree").ISimpleType<string>, [undefined]>;
+    /**
+     * #property
+     */
+    drawerPosition: import("@jbrowse/mobx-state-tree").IOptionalIType<import("@jbrowse/mobx-state-tree").ISimpleType<DrawerPosition>, [undefined]>;
+    /**
+     * #property
+     */
     drawerWidth: import("@jbrowse/mobx-state-tree").IOptionalIType<import("@jbrowse/mobx-state-tree").ISimpleType<number>, [undefined]>;
-    widgets: import("@jbrowse/mobx-state-tree").IMapType<import("@jbrowse/mobx-state-tree").IAnyType>;
-    activeWidgets: import("@jbrowse/mobx-state-tree").IMapType<import("@jbrowse/mobx-state-tree").IMaybe<import("@jbrowse/mobx-state-tree").IReferenceType<import("@jbrowse/mobx-state-tree").IAnyType>>>;
+    /**
+     * #property
+     */
+    widgets: import("@jbrowse/mobx-state-tree").IOptionalIType<import("@jbrowse/mobx-state-tree").IMapType<import("@jbrowse/mobx-state-tree").IAnyType>, [undefined]>;
+    /**
+     * #property
+     */
+    activeWidgets: import("@jbrowse/mobx-state-tree").IOptionalIType<import("@jbrowse/mobx-state-tree").IMapType<import("@jbrowse/mobx-state-tree").IMaybe<import("@jbrowse/mobx-state-tree").IReferenceType<import("@jbrowse/mobx-state-tree").IAnyType>>>, [undefined]>;
+    /**
+     * #property
+     */
     minimized: import("@jbrowse/mobx-state-tree").IOptionalIType<import("@jbrowse/mobx-state-tree").ISimpleType<boolean>, [undefined]>;
 }, {
-    readonly visibleWidget: any;
+    /**
+     * #getter
+     */
+    readonly visibleWidget: Widget | undefined;
 } & {
-    setDrawerPosition(arg: string): void;
-    updateDrawerWidth(drawerWidth: number): number;
-    resizeDrawer(distance: number): number;
-    addWidget(typeName: string, id: string, initialState?: {}, conf?: unknown): any;
+    /**
+     * #volatile
+     * true while the visible widget is shown in a modal dialog instead of the
+     * drawer. Volatile because a restored session that opened straight into a
+     * modal, with no drawer behind it, is disorienting
+     */
+    poppedOut: boolean;
+    /**
+     * #volatile
+     * set by a host with no room for a drawer column beside its views (a
+     * phone), so every widget shows in a modal instead
+     */
+    modalWidgets: boolean;
+} & {
+    /**
+     * #getter
+     * whether the drawer column is on screen: there is something to show, it
+     * is not minimized to the FAB, and it is not currently a modal instead.
+     *
+     * A getter rather than each host's own `&&`, because the hosts drifted --
+     * the app shell tested `poppedOut` and the embedded view did not, so the
+     * day a popout button reaches the embedded drawer header it would render
+     * the modal and the drawer at once.
+     */
+    readonly drawerVisible: boolean;
+    /**
+     * #getter
+     * whether the visible widget shows in a modal: popped out of the drawer,
+     * or on a host with no room for one
+     */
+    readonly modalWidgetVisible: boolean;
+} & {
+    /**
+     * #action
+     */
+    setDrawerPosition(arg: DrawerPosition): void;
+    /**
+     * #action
+     */
+    updateDrawerWidth(drawerWidth: number, availableWidth?: number): number;
+    /**
+     * #action
+     */
+    resizeDrawer(distance: number, availableWidth?: number): number;
+    /**
+     * #action
+     */
+    addWidget(typeName: string, id: string, initialState?: any, conf?: unknown): any;
+    /**
+     * #action
+     */
     showWidget(widget: any): void;
-    hasWidget(widget: any): boolean;
+    /**
+     * #action
+     */
     hideWidget(widget: any): void;
+    /**
+     * #action
+     */
     minimizeWidgetDrawer(): void;
+    /**
+     * #action
+     */
     showWidgetDrawer(): void;
+    /**
+     * #action
+     * show the visible widget in a modal dialog, freeing the drawer column
+     */
+    popoutWidget(): void;
+    /**
+     * #action
+     */
+    returnWidgetToDrawer(): void;
+    /**
+     * #action
+     */
+    setModalWidgets(flag: boolean): void;
+    /**
+     * #action
+     */
     hideAllWidgets(): void;
+    afterAttach(): void;
+} & {
+    /**
+     * #action
+     * the modal's close button: a popped-out widget goes back to the drawer,
+     * and with no drawer to go back to the widget closes
+     */
+    closeModalWidget(): void;
+    /**
+     * #action
+     * adds the widget, replacing one with the same id, and shows it
+     */
+    openWidget(typeName: string, id: string, initialState?: any, conf?: unknown): any;
+} & {
+    /**
+     * #action
+     * opens a configuration editor to configure the given thing,
+     * and sets the current task to be configuring it
+     * @param configuration - can be an MST model or a frozen/plain object with trackId
+     */
     editConfiguration(configuration: AnyConfigurationModel | {
         trackId: string;
+    }, opts?: {
+        expandedDisplayId?: string;
     }): void;
-    afterAttach(): void;
 }, import("@jbrowse/mobx-state-tree")._NotCustomized, import("@jbrowse/mobx-state-tree").ModelSnapshotType<{
-    drawerPosition: import("@jbrowse/mobx-state-tree").IOptionalIType<import("@jbrowse/mobx-state-tree").ISimpleType<string>, [undefined]>;
+    /**
+     * #property
+     */
+    drawerPosition: import("@jbrowse/mobx-state-tree").IOptionalIType<import("@jbrowse/mobx-state-tree").ISimpleType<DrawerPosition>, [undefined]>;
+    /**
+     * #property
+     */
     drawerWidth: import("@jbrowse/mobx-state-tree").IOptionalIType<import("@jbrowse/mobx-state-tree").ISimpleType<number>, [undefined]>;
-    widgets: import("@jbrowse/mobx-state-tree").IMapType<import("@jbrowse/mobx-state-tree").IAnyType>;
-    activeWidgets: import("@jbrowse/mobx-state-tree").IMapType<import("@jbrowse/mobx-state-tree").IMaybe<import("@jbrowse/mobx-state-tree").IReferenceType<import("@jbrowse/mobx-state-tree").IAnyType>>>;
+    /**
+     * #property
+     */
+    widgets: import("@jbrowse/mobx-state-tree").IOptionalIType<import("@jbrowse/mobx-state-tree").IMapType<import("@jbrowse/mobx-state-tree").IAnyType>, [undefined]>;
+    /**
+     * #property
+     */
+    activeWidgets: import("@jbrowse/mobx-state-tree").IOptionalIType<import("@jbrowse/mobx-state-tree").IMapType<import("@jbrowse/mobx-state-tree").IMaybe<import("@jbrowse/mobx-state-tree").IReferenceType<import("@jbrowse/mobx-state-tree").IAnyType>>>, [undefined]>;
+    /**
+     * #property
+     */
     minimized: import("@jbrowse/mobx-state-tree").IOptionalIType<import("@jbrowse/mobx-state-tree").ISimpleType<boolean>, [undefined]>;
 }>>;
+/** Session mixin MST type for a session that manages drawer widgets */
 export type SessionWithDrawerWidgetsType = ReturnType<typeof DrawerWidgetSessionMixin>;
+/** Instance of a session that manages drawer widgets */
 export type SessionWithDrawerWidgets = Instance<SessionWithDrawerWidgetsType>;
+/** Type guard for SessionWithDrawerWidgets */
 export declare function isSessionWithDrawerWidgets(session: IAnyStateTreeNode): session is SessionWithDrawerWidgets;