@jbrowse/app-core 4.3.0 → 5.0.0-beta.1

package/esm/RootMenu/index.js

@@ -1,71 +1,117 @@
 import { types } from '@jbrowse/mobx-state-tree';
+/**
+ * #stateModel RootAppMenuMixin
+ */
 export function RootAppMenuMixin() {
     return types
         .model({})
         .volatile(() => ({
+        // array reference is replaced (not mutated) so MobX observers detect the change
         mutableMenuActions: [],
     }))
-        .actions(self => ({
-        setMenus(newMenus) {
-            self.mutableMenuActions = [
-                ...self.mutableMenuActions,
-                { type: 'setMenus', newMenus },
-            ];
-        },
-        appendMenu(menuName) {
-            self.mutableMenuActions = [
-                ...self.mutableMenuActions,
-                { type: 'appendMenu', menuName },
-            ];
-        },
-        insertMenu(menuName, position) {
-            self.mutableMenuActions = [
-                ...self.mutableMenuActions,
-                {
-                    type: 'insertMenu',
-                    menuName,
-                    position,
-                },
-            ];
-        },
-        appendToMenu(menuName, menuItem) {
-            self.mutableMenuActions = [
-                ...self.mutableMenuActions,
-                {
-                    type: 'appendToMenu',
-                    menuName,
-                    menuItem,
-                },
-            ];
-        },
-        insertInMenu(menuName, menuItem, position) {
-            self.mutableMenuActions.push({
-                type: 'insertInMenu',
-                menuName,
-                menuItem,
-                position,
-            });
-        },
-        appendToSubMenu(menuPath, menuItem) {
-            self.mutableMenuActions = [
-                ...self.mutableMenuActions,
-                {
-                    type: 'appendToSubMenu',
-                    menuPath,
-                    menuItem,
-                },
-            ];
-        },
-        insertInSubMenu(menuPath, menuItem, position) {
-            self.mutableMenuActions = [
-                ...self.mutableMenuActions,
-                {
-                    type: 'insertInSubMenu',
-                    menuPath,
+        .actions(self => {
+        function pushAction(action) {
+            self.mutableMenuActions = [...self.mutableMenuActions, action];
+        }
+        return {
+            /**
+             * #action
+             * Replace the menu bar wholesale. Item contributions recorded before
+             * this one are dropped along with the menus they targeted, so a plugin
+             * adding to the existing bar wants `appendToMenu` instead.
+             *
+             * @param newMenus - The complete new set of top-level menus.
+             */
+            setMenus(newMenus) {
+                pushAction({ type: 'setMenus', newMenus });
+            },
+            /**
+             * #action
+             * Add a top-level menu, if the app bar does not already have one with
+             * this name.
+             *
+             * @param menuName - Name of the menu to add.
+             */
+            appendMenu(menuName) {
+                pushAction({ type: 'addMenu', menuName });
+            },
+            /**
+             * #action
+             * Insert a top-level menu, if the app bar does not already have one
+             * with this name.
+             *
+             * @param menuName - Name of the menu to insert.
+             *
+             * @param position - Position to insert menu. If negative, counts from the
+             * end, e.g. `insertMenu('My Menu', -1)` will insert the menu as the
+             * second-to-last one.
+             */
+            insertMenu(menuName, position) {
+                pushAction({ type: 'addMenu', menuName, position });
+            },
+            /**
+             * #action
+             * Add a menu item to a top-level menu, creating the menu if it does not
+             * exist.
+             *
+             * @param menuName - Name of the top-level menu to append to.
+             *
+             * @param menuItem - Menu item to append.
+             */
+            appendToMenu(menuName, menuItem) {
+                pushAction({ type: 'addItem', menuPath: [menuName], menuItem });
+            },
+            /**
+             * #action
+             * Insert a menu item into a top-level menu, creating the menu if it
+             * does not exist.
+             *
+             * @param menuName - Name of the top-level menu to insert into
+             *
+             * @param menuItem - Menu item to insert
+             *
+             * @param position - Position to insert menu item. If negative, counts
+             * from the end, e.g. `insertInMenu('My Menu', item, -1)` will insert the
+             * item as the second-to-last one.
+             */
+            insertInMenu(menuName, menuItem, position) {
+                pushAction({
+                    type: 'addItem',
+                    menuPath: [menuName],
                     menuItem,
                     position,
-                },
-            ];
-        },
-    }));
+                });
+            },
+            /**
+             * #action
+             * Add a menu item to a sub-menu, creating any part of the path that
+             * does not exist.
+             *
+             * @param menuPath - Path to the sub-menu to add to, starting with the
+             * top-level menu (e.g. `['File', 'Insert']`).
+             *
+             * @param menuItem - Menu item to append.
+             */
+            appendToSubMenu(menuPath, menuItem) {
+                pushAction({ type: 'addItem', menuPath, menuItem });
+            },
+            /**
+             * #action
+             * Insert a menu item into a sub-menu, creating any part of the path
+             * that does not exist.
+             *
+             * @param menuPath - Path to the sub-menu to add to, starting with the
+             * top-level menu (e.g. `['File', 'Insert']`).
+             *
+             * @param menuItem - Menu item to insert.
+             *
+             * @param position - Position to insert menu item. If negative, counts
+             * from the end, e.g. `insertInSubMenu(path, item, -1)` will insert the
+             * item as the second-to-last one.
+             */
+            insertInSubMenu(menuPath, menuItem, position) {
+                pushAction({ type: 'addItem', menuPath, menuItem, position });
+            },
+        };
+    });
 }

package/esm/SessionSpec/index.d.ts

@@ -0,0 +1,6 @@
+export { buildLgvInit, buildLgvInitFromParams, hubConnectionSpec, readHubUrlParam, readNavParam, readTracklistParam, shortHubLabel, splitHighlights, } from './lgvUrlInit.ts';
+export { addSessionTracks, loadSessionSpec } from './loadSessionSpec.ts';
+export { parseSessionSpecUrl } from './parseSessionSpecUrl.ts';
+export type { LgvUrlInit } from './lgvUrlInit.ts';
+export type { ParsedSessionSpec } from './parseSessionSpecUrl.ts';
+export type { LayoutNode, ViewSpec } from './types.ts';

package/esm/SessionSpec/index.js

@@ -0,0 +1,3 @@
+export { buildLgvInit, buildLgvInitFromParams, hubConnectionSpec, readHubUrlParam, readNavParam, readTracklistParam, shortHubLabel, splitHighlights, } from './lgvUrlInit.js';
+export { addSessionTracks, loadSessionSpec } from './loadSessionSpec.js';
+export { parseSessionSpecUrl } from './parseSessionSpecUrl.js';

package/esm/SessionSpec/lgvUrlInit.d.ts

@@ -0,0 +1,79 @@
+export interface LgvUrlInit {
+    loc?: string;
+    assembly?: string;
+    tracks?: string[];
+    tracklist?: boolean;
+    nav?: boolean;
+    highlight?: string[];
+    displayedRegionNames?: string[];
+}
+export declare function splitHighlights(str: string): string[];
+/**
+ * `&tracklist=` — only the literal `true` turns the track selector on.
+ *
+ * Absent stays absent rather than collapsing into the param's default:
+ * buildLgvInit's result is layered over a defaultSession's own pending init, so
+ * a `false` synthesized here would overwrite what that session set.
+ */
+export declare function readTracklistParam(value: string | undefined): boolean | undefined;
+/**
+ * `&nav=` — anything but the literal `false` leaves the navigation bar on.
+ *
+ * The opposite default to tracklist above, and deliberately so: the nav bar is
+ * on unless a link turns it off, the track selector is off unless a link turns
+ * it on. Absent stays absent for the same reason as tracklist.
+ */
+export declare function readNavParam(value: string | undefined): boolean | undefined;
+/**
+ * Normalizes already-decoded shorthand values into an LGV init.
+ *
+ * A param the URL omits is left off the result rather than set to undefined:
+ * jbrowse-web's applyDefaultSessionViewInit merges this over the view's own
+ * pending init, and a present-but-undefined key there would erase what the
+ * defaultSession set.
+ */
+export declare function buildLgvInit(args: {
+    loc?: string;
+    tracks?: string;
+    assembly?: string;
+    tracklist?: boolean;
+    nav?: boolean;
+    highlight?: string;
+    regions?: string;
+}): LgvUrlInit;
+/**
+ * `&hubURL=` — a comma-separated list of hub.txt urls.
+ *
+ * Empty entries are dropped, so `&hubURL=` and `&hubURL=,,` are no hubs at all
+ * rather than a list of blanks. jbrowse-web learned that the hard way: a
+ * present-but-empty param is still truthy, which routed the load to a hub
+ * builder with no url to connect to and produced a session with nothing in it
+ * and no diagnostic.
+ */
+export declare function readHubUrlParam(value: string | undefined): string[];
+/**
+ * A short, readable label for a hub connection, before its hub.txt has been
+ * read: the second-to-last path segment, which for `…/myHub/hub.txt` is the
+ * hub's own directory. Beats showing the whole url in a track-selector category
+ * header.
+ */
+export declare function shortHubLabel(url: string): string;
+/**
+ * The `sessionConnections` entry for a hub url — the spec vocabulary for "attach
+ * this track hub", which loadSessionSpec registers before it launches any view.
+ */
+export declare function hubConnectionSpec(url: string): {
+    type: string;
+    connectionId: string;
+    name: string;
+    hubTxtLocation: {
+        uri: string;
+        locationType: string;
+    };
+};
+/**
+ * The same init, read straight off a link's params. jbrowse-web decodes these
+ * into its loader's own properties first (they have to survive an HMR reload),
+ * so it calls buildLgvInit above; a caller holding a whole URL wants this.
+ */
+export declare function buildLgvInitFromParams(params: URLSearchParams): LgvUrlInit;

package/esm/SessionSpec/lgvUrlInit.js

@@ -0,0 +1,158 @@
+import { parseRegionNames } from '@jbrowse/core/util';
+// split a space-separated &highlight= URL param into individual highlights.
+// spaces inside a JSON object ({...}) are not treated as delimiters, so a
+// highlight like {"refName":"chr1","start":1,"end":2,"label":"my region"}
+// survives intact alongside plain loc strings
+export function splitHighlights(str) {
+    const out = [];
+    let depth = 0;
+    let cur = '';
+    for (const ch of str) {
+        if (ch === '{') {
+            depth++;
+        }
+        if (ch === '}') {
+            depth = Math.max(0, depth - 1);
+        }
+        if (ch === ' ' && depth === 0) {
+            if (cur) {
+                out.push(cur);
+            }
+            cur = '';
+        }
+        else {
+            cur += ch;
+        }
+    }
+    if (cur) {
+        out.push(cur);
+    }
+    return out;
+}
+/**
+ * `&tracklist=` — only the literal `true` turns the track selector on.
+ *
+ * Absent stays absent rather than collapsing into the param's default:
+ * buildLgvInit's result is layered over a defaultSession's own pending init, so
+ * a `false` synthesized here would overwrite what that session set.
+ */
+export function readTracklistParam(value) {
+    return value === undefined ? undefined : value === 'true';
+}
+/**
+ * `&nav=` — anything but the literal `false` leaves the navigation bar on.
+ *
+ * The opposite default to tracklist above, and deliberately so: the nav bar is
+ * on unless a link turns it off, the track selector is off unless a link turns
+ * it on. Absent stays absent for the same reason as tracklist.
+ */
+export function readNavParam(value) {
+    return value === undefined ? undefined : value !== 'false';
+}
+/**
+ * Normalizes already-decoded shorthand values into an LGV init.
+ *
+ * A param the URL omits is left off the result rather than set to undefined:
+ * jbrowse-web's applyDefaultSessionViewInit merges this over the view's own
+ * pending init, and a present-but-undefined key there would erase what the
+ * defaultSession set.
+ */
+export function buildLgvInit(args) {
+    const { loc, tracks, assembly, tracklist, nav, highlight, regions } = args;
+    const init = {};
+    if (loc !== undefined) {
+        init.loc = loc;
+    }
+    if (assembly !== undefined) {
+        init.assembly = assembly;
+    }
+    if (tracks !== undefined) {
+        init.tracks = tracks.split(',');
+    }
+    if (tracklist !== undefined) {
+        init.tracklist = tracklist;
+    }
+    if (nav !== undefined) {
+        init.nav = nav;
+    }
+    if (highlight !== undefined) {
+        init.highlight = splitHighlights(highlight);
+    }
+    if (regions !== undefined) {
+        // restrict a whole-genome view (no loc) to these named chromosomes, in
+        // order; resolved through assembly aliases in afterAttach's showNamedRegions
+        //
+        // Through core's parser, the same one the import forms' chromosome boxes
+        // use, rather than a bare split: this is one syntax with one meaning, and
+        // the second reading of it dropped `chr2` from `&regions=chr1,%20chr2`
+        // without a word. Empty entries go with it — a present-but-empty
+        // `&regions=` is still truthy, and the list of one empty name it used to
+        // produce reported itself as having matched nothing. Same trap as
+        // readHubUrlParam below.
+        const names = parseRegionNames(regions);
+        if (names.length) {
+            init.displayedRegionNames = names;
+        }
+    }
+    return init;
+}
+/**
+ * `&hubURL=` — a comma-separated list of hub.txt urls.
+ *
+ * Empty entries are dropped, so `&hubURL=` and `&hubURL=,,` are no hubs at all
+ * rather than a list of blanks. jbrowse-web learned that the hard way: a
+ * present-but-empty param is still truthy, which routed the load to a hub
+ * builder with no url to connect to and produced a session with nothing in it
+ * and no diagnostic.
+ */
+export function readHubUrlParam(value) {
+    return value?.split(',').filter(Boolean) ?? [];
+}
+/**
+ * A short, readable label for a hub connection, before its hub.txt has been
+ * read: the second-to-last path segment, which for `…/myHub/hub.txt` is the
+ * hub's own directory. Beats showing the whole url in a track-selector category
+ * header.
+ */
+export function shortHubLabel(url) {
+    try {
+        const segments = new URL(url).pathname.split('/').filter(Boolean);
+        return segments.at(-2) ?? segments.at(-1) ?? url;
+    }
+    catch {
+        return url;
+    }
+}
+/**
+ * The `sessionConnections` entry for a hub url — the spec vocabulary for "attach
+ * this track hub", which loadSessionSpec registers before it launches any view.
+ */
+export function hubConnectionSpec(url) {
+    return {
+        type: 'UCSCTrackHubConnection',
+        connectionId: url,
+        name: shortHubLabel(url),
+        hubTxtLocation: { uri: url, locationType: 'UriLocation' },
+    };
+}
+// URLSearchParams.get returns null for an absent param, and every reader here
+// distinguishes absent from present-and-empty
+function read(params, key) {
+    return params.get(key) ?? undefined;
+}
+/**
+ * The same init, read straight off a link's params. jbrowse-web decodes these
+ * into its loader's own properties first (they have to survive an HMR reload),
+ * so it calls buildLgvInit above; a caller holding a whole URL wants this.
+ */
+export function buildLgvInitFromParams(params) {
+    return buildLgvInit({
+        loc: read(params, 'loc'),
+        assembly: read(params, 'assembly'),
+        tracks: read(params, 'tracks'),
+        tracklist: readTracklistParam(read(params, 'tracklist')),
+        nav: readNavParam(read(params, 'nav')),
+        highlight: read(params, 'highlight'),
+        regions: read(params, 'regions'),
+    });
+}

package/esm/SessionSpec/loadSessionSpec.d.ts

@@ -0,0 +1,21 @@
+import type { LayoutNode, ViewSpec } from './types.ts';
+import type PluginManager from '@jbrowse/core/PluginManager';
+import type { AbstractSessionModel } from '@jbrowse/core/util';
+/**
+ * Register `&sessionTracks=` / a spec's `sessionTracks` into a session.
+ *
+ * Exported because the hub launch needs it too and must not reimplement it.
+ *
+ * A track that fails to register does not cost the caller the rest of them —
+ * same reasoning as the per-connection and per-view try/catch around it, one
+ * layer down.
+ */
+export declare function addSessionTracks(session: AbstractSessionModel | undefined, tracks: Record<string, unknown>[]): void;
+export declare function loadSessionSpec({ views, sessionAssemblies, sessionConnections, sessionTracks, layout, sessionName, }: {
+    views: ViewSpec[];
+    sessionAssemblies?: Record<string, unknown>[];
+    sessionConnections?: Record<string, unknown>[];
+    sessionTracks?: Record<string, unknown>[];
+    layout?: LayoutNode;
+    sessionName?: string;
+}, pluginManager: PluginManager): Promise<void>;