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

package/esm/RootMenu/index.d.ts

@@ -1,13 +1,79 @@
-import type { Menu, MenuAction } from '../menus.ts';
-import type { MenuItem } from '@jbrowse/core/ui/Menu';
+import type { MenuAction } from '../menus.ts';
+import type { MenuItem } from '@jbrowse/core/ui/menuItems';
+/**
+ * #stateModel RootAppMenuMixin
+ */
 export declare function RootAppMenuMixin(): import("@jbrowse/mobx-state-tree").IModelType<{}, {
     mutableMenuActions: MenuAction[];
 } & {
-    setMenus(newMenus: Menu[]): void;
+    /**
+     * #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: string): void;
+    /**
+     * #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: string, position: number): void;
+    /**
+     * #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: string, menuItem: MenuItem): void;
+    /**
+     * #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: string, menuItem: MenuItem, position: number): void;
+    /**
+     * #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: string[], menuItem: MenuItem): void;
+    /**
+     * #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: string[], menuItem: MenuItem, position: number): void;
 }, import("@jbrowse/mobx-state-tree")._NotCustomized, import("@jbrowse/mobx-state-tree")._NotCustomized>;

package/esm/RootMenu/index.js

@@ -1,71 +1,106 @@
 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
+             * 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, launchSpecView, launchableSpecView, loadSessionSpec, viewTypeProblem, } 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, launchSpecView, launchableSpecView, loadSessionSpec, viewTypeProblem, } 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,161 @@
+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;
+    }
+    // empty entries dropped, like `regions`: `&tracks=a,` asked for no track
+    // named ''
+    const trackIds = tracks?.split(',').filter(Boolean);
+    if (trackIds?.length) {
+        init.tracks = trackIds;
+    }
+    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,75 @@
+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;
+/**
+ * Why one view type cannot launch from a spec here, or nothing. Two causes,
+ * two messages: the type is unknown at all (a typo, or a plugin that was not
+ * loaded), or it exists but nothing taught it how to launch from a spec, which
+ * only the view's plugin can fix.
+ */
+export declare function viewTypeProblem(pluginManager: PluginManager, type: string): string | undefined;
+/**
+ * A spec view entry as its launcher takes it, and what its type does not take.
+ *
+ * The same classification a view snapshot gets, run here because a spec never
+ * becomes one: `LaunchView-<type>` takes these keys as arguments, so
+ * `withLaunchInput`'s partition never sees them and nothing names a typo.
+ * `{type: 'LinearGenomeView', asembly: 'volvox'}` reported only the launcher's
+ * downstream "No assembly provided", on the one surface written by hand with no
+ * compiler and no editor behind it.
+ *
+ * A view type that registers no launch keys classifies nothing: its launcher's
+ * vocabulary is undeclared, so every argument would read as a typo. A lazily
+ * registered type declares its properties on a state model that is not loaded
+ * yet, so it is loaded first — the launch would have loaded it anyway.
+ */
+export declare function launchableSpecView(pluginManager: PluginManager, spec: ViewSpec): Promise<{
+    view: ViewSpec;
+    problem?: string;
+}>;
+/**
+ * Launch one spec view into the session through its `LaunchView-<type>`
+ * extension point, the same door `loadSessionSpec` uses for each of its views
+ * — so `jb.addView` and a spec agree on what a view entry means, a
+ * ProteinView's `connectedView` included.
+ *
+ * Strict so a launch handler that throws (missing/invalid assembly, unresolved
+ * track, ...) is returned as a failure instead of being swallowed by the plain
+ * extension-point runner, which would leave a silent empty session. A handler
+ * that legitimately no-ops returns normally and is unaffected.
+ *
+ * `created` is EVERY view the launch added, in creation order: a connected
+ * ProteinView creates its genome view and then itself. `view` is the entry's
+ * own, the one of the spec's type, which is where `displayName` goes — it used
+ * to land on the genome view a ProteinView opened first, and the structure came
+ * up "Untitled view". `type` is the dispatch key, not a setting: forwarding it
+ * would land in the view's launch blob and trip the "ignored unknown key(s):
+ * type" warning meant to catch typos.
+ */
+export declare function launchSpecView(session: AbstractSessionModel | undefined, pluginManager: PluginManager, spec: ViewSpec): Promise<{
+    created: import("@jbrowse/core/util").AbstractViewModel[];
+    view: import("@jbrowse/core/util").AbstractViewModel | undefined;
+    failure?: {
+        message: string;
+        cause: unknown;
+    } | undefined;
+}>;
+export interface SessionSpec {
+    views: ViewSpec[];
+    sessionAssemblies?: Record<string, unknown>[];
+    sessionConnections?: Record<string, unknown>[];
+    sessionTracks?: Record<string, unknown>[];
+    layout?: LayoutNode;
+    sessionName?: string;
+}
+export declare function loadSessionSpec(spec: SessionSpec, pluginManager: PluginManager): Promise<void>;