@jbrowse/core 4.3.0 → 5.0.0-beta.10

package/esm/BaseFeatureWidget/stateModelFactory.js

@@ -1,95 +1,194 @@
-import { addDisposer, types } from '@jbrowse/mobx-state-tree';
-import { autorun } from 'mobx';
-import { getConf } from "../configuration/index.js";
-import { getSession } from "../util/index.js";
-import { SequenceFeatureDetailsF } from "./SequenceFeatureDetails/model.js";
-import { formatSubfeatures } from "./util.js";
-import { ElementId } from "../util/types/mst.js";
+import { getEnv, isStateTreeNode, types } from '@jbrowse/mobx-state-tree';
+import { hydrateTrackConfig } from '../configuration/index.js';
+import { getSession } from '../util/index.js';
+import { ElementId } from '../util/types/mst.js';
+import { SequenceFeatureDetailsF } from './SequenceFeatureDetails/model.js';
+import { applyFormatDetails, formatDetailsNumber } from './formatDetails.js';
+function isTrackNode(thing) {
+    return isStateTreeNode(thing) && 'type' in thing && 'configuration' in thing;
+}
+/**
+ * #stateModel BaseFeatureWidget
+ * The feature-details panel. `featureData` is the clicked feature with the
+ * track's and the session's `formatDetails` callbacks applied, derived on read
+ * from the raw feature the widget was opened with, so the same widget follows a
+ * config edit and survives its track being closed.
+ */
 export function stateModelFactory(pluginManager) {
     return types
         .model('BaseFeatureWidget', {
+        /**
+         * #property
+         */
         id: ElementId,
+        /**
+         * #property
+         */
         type: types.literal('BaseFeatureWidget'),
-        featureData: types.frozen(),
-        formattedFields: types.frozen(),
-        unformattedFeatureData: types.frozen(),
+        /**
+         * #property
+         * the feature as the click handed it over, before any callback ran.
+         * Persisted as `featureData`
+         */
+        unformattedFeatureData: types.optional(types.frozen(), undefined),
+        /**
+         * #property
+         */
         view: types.safeReference(pluginManager.pluggableMstType('view', 'stateModel')),
+        /**
+         * #property
+         */
         track: types.safeReference(pluginManager.pluggableMstType('track', 'stateModel')),
+        /**
+         * #property
+         */
         trackId: types.maybe(types.string),
+        /**
+         * #property
+         */
         trackType: types.maybe(types.string),
-        maxDepth: types.maybe(types.number),
+        /**
+         * #property
+         */
         sequenceFeatureDetails: types.optional(SequenceFeatureDetailsF(), {}),
-        descriptions: types.frozen(),
+        /**
+         * #property
+         */
+        descriptions: types.optional(types.frozen(), undefined),
+        /**
+         * #property
+         * names the feature this one was reached through, when it was reached
+         * through one -- a transcript clicked inside its gene
+         */
+        parentFeature: types.optional(types.frozen(), undefined),
     })
         .volatile(() => ({
-        error: undefined,
+        /**
+         * #volatile
+         * genomic base currently hovered in this widget's sequence panel, read by
+         * the LGV crosshair overlay
+         */
+        sequenceHoverPosition: undefined,
     }))
-        .actions(self => ({
-        setFeatureData(featureData) {
-            self.unformattedFeatureData = featureData;
+        .views(self => ({
+        /**
+         * #getter
+         * the config the track tier of `formatDetails` reads. The open track's
+         * own while it is open; after it is closed, the session's copy of the
+         * same config, which is why the widget records `trackId`
+         */
+        get trackConfiguration() {
+            const { track, trackId } = self;
+            if (track) {
+                return track.configuration;
+            }
+            if (!trackId) {
+                return undefined;
+            }
+            const conf = getSession(self).getTrackById(trackId);
+            return conf === undefined || isStateTreeNode(conf)
+                ? conf
+                : hydrateTrackConfig(getEnv(self).pluginManager, conf);
         },
-        clearFeatureData() {
-            self.featureData = undefined;
+    }))
+        .views(self => ({
+        get formatDetailsTiers() {
+            return {
+                session: getSession(self).configuration,
+                track: self.trackConfiguration,
+            };
+        },
+    }))
+        .views(self => ({
+        get formatted() {
+            const { unformattedFeatureData } = self;
+            if (!unformattedFeatureData) {
+                return {};
+            }
+            try {
+                return {
+                    feature: applyFormatDetails(self.formatDetailsTiers, unformattedFeatureData),
+                };
+            }
+            catch (e) {
+                const error = new Error(`Error running the formatDetails callbacks: ${e}`, { cause: e });
+                console.error(error);
+                return { error };
+            }
         },
-        setFormattedData(feat) {
-            self.featureData = feat;
+        /**
+         * #getter
+         * levels of subfeature card the panel renders; unset means no limit
+         */
+        get maxDepth() {
+            return formatDetailsNumber(self.formatDetailsTiers, 'maxDepth');
         },
-        setExtra(type, trackId, maxDepth) {
-            self.trackId = trackId;
-            self.trackType = type;
-            self.maxDepth = maxDepth;
+    }))
+        .views(self => ({
+        /**
+         * #getter
+         * the feature with every `formatDetails` callback applied
+         */
+        get featureData() {
+            return self.formatted.feature;
         },
-        setError(e) {
-            self.error = e;
+        /**
+         * #getter
+         */
+        get error() {
+            return self.formatted.error;
         },
     }))
         .actions(self => ({
-        afterCreate() {
-            addDisposer(self, autorun(function featureWidgetAutorun() {
-                try {
-                    const { unformattedFeatureData, track } = self;
-                    const session = getSession(self);
-                    if (track) {
-                        self.setExtra(track.type, track.configuration.trackId, getConf(track, ['formatDetails', 'maxDepth']));
-                    }
-                    if (unformattedFeatureData) {
-                        const feature = structuredClone(unformattedFeatureData);
-                        const combine = (arg2, feature) => ({
-                            ...getConf(session, ['formatDetails', arg2], { feature }),
-                            ...getConf(track, ['formatDetails', arg2], { feature }),
-                        });
-                        if (track) {
-                            feature.__jbrowsefmt = combine('feature', feature);
-                            formatSubfeatures(feature, getConf(track, ['formatDetails', 'depth']), sub => {
-                                sub.__jbrowsefmt = combine('subfeatures', sub);
-                            });
-                        }
-                        self.setFormattedData(feature);
-                    }
-                }
-                catch (e) {
-                    console.error(e);
-                    self.setError(e);
-                }
-            }, { name: 'FeatureWidget' }));
+        /**
+         * #action
+         */
+        setSequenceHoverPosition(pos) {
+            // skip no-op updates: mousemove fires per pixel but the base under the
+            // cursor changes far less often, and each change re-renders the LGV
+            // crosshair overlay
+            const prev = self.sequenceHoverPosition;
+            const same = prev === pos ||
+                (prev?.refName === pos?.refName &&
+                    prev?.start === pos?.start &&
+                    prev?.end === pos?.end);
+            if (!same) {
+                self.sequenceHoverPosition = pos;
+            }
+        },
+        /**
+         * #action
+         */
+        setFeatureData(featureData) {
+            self.unformattedFeatureData = featureData;
+        },
+        /**
+         * #action
+         */
+        clearFeatureData() {
+            self.unformattedFeatureData = undefined;
         },
     }))
-        .preProcessSnapshot(snap => {
-        const { featureData, finalizedFeatureData, ...rest } = snap;
+        .preProcessSnapshot((snap) => {
+        const { featureData, ...rest } = snap ?? {};
+        // here rather than in afterAttach: a second feature opened into the same
+        // widget id reconciles onto the existing node, which never re-attaches
+        const { track } = rest;
         return {
             unformattedFeatureData: featureData,
-            featureData: finalizedFeatureData,
+            ...(isTrackNode(track)
+                ? { trackId: track.configuration.trackId, trackType: track.type }
+                : {}),
             ...rest,
         };
     })
         .postProcessSnapshot(snap => {
-        const { unformattedFeatureData, featureData, ...rest } = snap;
-        const s2 = JSON.stringify(featureData, (_, v) => v === undefined ? null : v);
-        const featureTooLargeToBeSerialized = !s2 || s2.length > 2_000_000;
+        const { unformattedFeatureData, ...rest } = snap;
+        // undefined when there is no feature
+        const json = JSON.stringify(unformattedFeatureData);
+        const tooLargeToPersist = !json || json.length > 2_000_000;
         return {
-            finalizedFeatureData: featureTooLargeToBeSerialized
-                ? undefined
-                : JSON.parse(s2),
+            featureData: tooLargeToPersist ? undefined : unformattedFeatureData,
             ...rest,
         };
     });

package/esm/BaseFeatureWidget/types.d.ts

@@ -1,22 +1,29 @@
-import type React from 'react';
-import type { BaseFeatureWidgetModel } from './stateModelFactory.ts';
+import type { MenuItem } from '../ui/MenuTypes.ts';
 import type { SimpleFeatureSerialized } from '../util/simpleFeature.ts';
+import type { SequenceFeatureDetailsModel, SequenceHoverTarget } from './SequenceFeatureDetails/model.ts';
+import type { IStateTreeNode } from '@jbrowse/mobx-state-tree';
+import type React from 'react';
+export interface FeatureDetailsModel extends IStateTreeNode, SequenceHoverTarget {
+    maxDepth: number | undefined;
+    sequenceFeatureDetails: SequenceFeatureDetailsModel;
+    view: {
+        assemblyNames: string[];
+    } | undefined;
+}
 export interface Descriptors {
     [key: string]: React.ReactNode | Descriptors;
 }
+export type FeatureFormatter = (value: unknown, key: string, index?: number) => React.ReactNode;
+/** Menu items for one attribute's value, offered from a button on its row. */
+export type FieldActions = (path: string[], value: unknown) => MenuItem[];
 export interface BaseProps extends BaseCardProps {
     feature: SimpleFeatureSerialized;
-    formatter?: (val: unknown, key: string) => React.ReactNode;
+    formatter?: FeatureFormatter;
     descriptions?: Descriptors;
-    model?: BaseFeatureWidgetModel;
 }
 export interface BaseCardProps {
     title?: string;
     defaultExpanded?: boolean;
     children?: React.ReactNode;
 }
-export interface SerializedFeat {
-    [key: string]: unknown;
-    subfeatures?: Record<string, unknown>[];
-}
 export type MaybeSerializedFeat = SimpleFeatureSerialized | undefined;

package/esm/BaseFeatureWidget/util.d.ts

@@ -1,20 +1,11 @@
-import type { SerializedFeat } from './types.tsx';
-import type { SimpleFeatureSerialized } from '../util/index.ts';
 export interface Feat {
     start: number;
     end: number;
     type?: string;
     name?: string;
-    id?: string;
+    id?: string | number;
     phase?: number;
 }
-export interface ParentFeat extends Feat {
-    uniqueId: string;
-    strand?: number;
-    refName: string;
-    subfeatures?: Feat[];
-    parentId?: string;
-}
 export interface SeqState {
     seq: string;
     upstream?: string;
@@ -23,32 +14,6 @@ export interface SeqState {
 export interface ErrorState {
     error: string;
 }
-export declare function stitch(subfeats: {
-    start: number;
-    end: number;
-}[], sequence: string): string;
 export declare function filterSuccessiveElementsWithSameStartAndEndCoord(list: Feat[]): Feat[];
-export declare function revlist(list: Feat[], seqlen: number): {
-    start: number;
-    end: number;
-    type?: string;
-    name?: string;
-    id?: string;
-    phase?: number;
-}[];
-export declare function calculateUTRs(cds: Feat[], exons: Feat[]): {
-    type: string;
-    start: number;
-    end: number;
-    name?: string;
-    id?: string;
-    phase?: number;
-}[];
-export declare function calculateUTRs2(cds: Feat[], parentFeat: Feat): {
-    type: string;
-    start: number;
-    end: number;
-}[];
 export declare function ellipses(slug: string): string;
-export declare function replaceUndefinedWithNull(obj: SimpleFeatureSerialized): any;
-export declare function formatSubfeatures(obj: SerializedFeat, depth: number, parse: (obj: Record<string, unknown>) => void, currentDepth?: number, returnObj?: Record<string, unknown>): void;
+export declare function getStrandStr(strand: number | undefined): "" | "(+)" | "(-)";

package/esm/BaseFeatureWidget/util.js

@@ -1,95 +1,14 @@
-export function stitch(subfeats, sequence) {
-    return subfeats.map(sub => sequence.slice(sub.start, sub.end)).join('');
-}
+// filter items if they have the same "ID" or location
 function getItemId(feat) {
     return `${feat.start}-${feat.end}`;
 }
+// filters if successive elements share same start/end
 export function filterSuccessiveElementsWithSameStartAndEndCoord(list) {
     return list.filter((item, pos, ary) => !pos || getItemId(item) !== getItemId(ary[pos - 1]));
 }
-export function revlist(list, seqlen) {
-    return list
-        .map(sub => ({
-        ...sub,
-        start: seqlen - sub.end,
-        end: seqlen - sub.start,
-    }))
-        .sort((a, b) => a.start - b.start);
-}
-export function calculateUTRs(cds, exons) {
-    if (!cds.length) {
-        return [];
-    }
-    if (exons.length < cds.length) {
-        console.warn('exons.length less than cds.length, cant calculate UTR properly', { exons, cds });
-        return [];
-    }
-    const firstCds = cds.at(0);
-    const lastCds = cds.at(-1);
-    const firstCdsIdx = exons.findIndex(exon => exon.end >= firstCds.start && exon.start <= firstCds.start);
-    const lastCdsIdx = exons.findIndex(exon => exon.end >= lastCds.end && exon.start <= lastCds.end);
-    const lastCdsExon = exons[lastCdsIdx];
-    const firstCdsExon = exons[firstCdsIdx];
-    const fivePrimeUTRs = [
-        ...exons.slice(0, firstCdsIdx),
-        {
-            start: firstCdsExon.start,
-            end: firstCds.start,
-        },
-    ].map(elt => ({
-        ...elt,
-        type: 'five_prime_UTR',
-    }));
-    const threePrimeUTRs = [
-        {
-            start: lastCds.end,
-            end: lastCdsExon.end,
-        },
-        ...exons.slice(lastCdsIdx + 1),
-    ].map(elt => ({
-        ...elt,
-        type: 'three_prime_UTR',
-    }));
-    return [...fivePrimeUTRs, ...threePrimeUTRs];
-}
-export function calculateUTRs2(cds, parentFeat) {
-    if (!cds.length) {
-        return [];
-    }
-    const firstCds = cds.at(0);
-    const lastCds = cds.at(-1);
-    const fivePrimeUTRs = [
-        {
-            start: parentFeat.start,
-            end: firstCds.start,
-        },
-    ].map(elt => ({
-        ...elt,
-        type: 'five_prime_UTR',
-    }));
-    const threePrimeUTRs = [
-        {
-            start: lastCds.end,
-            end: parentFeat.end,
-        },
-    ].map(elt => ({
-        ...elt,
-        type: 'three_prime_UTR',
-    }));
-    return [...fivePrimeUTRs, ...threePrimeUTRs];
-}
 export function ellipses(slug) {
     return slug.length > 20 ? `${slug.slice(0, 20)}...` : slug;
 }
-export function replaceUndefinedWithNull(obj) {
-    return JSON.parse(JSON.stringify(obj, (_, v) => (v === undefined ? null : v)));
-}
-export function formatSubfeatures(obj, depth, parse, currentDepth = 0, returnObj = {}) {
-    if (depth <= currentDepth) {
-        return;
-    }
-    obj.subfeatures?.map(sub => {
-        formatSubfeatures(sub, depth, parse, currentDepth + 1, returnObj);
-        parse(sub);
-    });
+export function getStrandStr(strand) {
+    return strand === -1 ? '(-)' : strand === 1 ? '(+)' : '';
 }

package/esm/CorePlugin.js

@@ -1,23 +1,28 @@
-import { lazy } from 'react';
-import { configSchema, stateModelFactory } from "./BaseFeatureWidget/index.js";
-import Plugin from "./Plugin.js";
-import CytobandAdapterF from "./data_adapters/CytobandAdapter/index.js";
-import WidgetType from "./pluggableElementTypes/WidgetType.js";
-import * as coreRpcMethods from "./rpc/coreRpcMethods.js";
+import { configSchema, stateModelFactory } from './BaseFeatureWidget/index.js';
+import Plugin from './Plugin.js';
+import CytobandAdapterF from './data_adapters/CytobandAdapter/index.js';
+import WidgetType from './pluggableElementTypes/WidgetType.js';
+import * as coreRpcMethods from './rpc/coreRpcMethods.js';
+import { installFormatGuessers } from './util/formatGuessers.js';
+import { lazyWithPreload } from './util/lazyWithPreload.js';
+// the core plugin, which registers types that ALL JBrowse applications are
+// expected to need.
 export default class CorePlugin extends Plugin {
     name = 'CorePlugin';
     install(pluginManager) {
+        // register all our core rpc methods
         for (const RpcMethod of Object.values(coreRpcMethods)) {
             pluginManager.addRpcMethod(() => new RpcMethod(pluginManager));
         }
         CytobandAdapterF(pluginManager);
+        installFormatGuessers(pluginManager);
         pluginManager.addWidgetType(() => {
             return new WidgetType({
                 name: 'BaseFeatureWidget',
                 heading: 'Feature details',
                 configSchema,
                 stateModel: stateModelFactory(pluginManager),
-                ReactComponent: lazy(() => import("./BaseFeatureWidget/BaseFeatureDetail/index.js")),
+                ReactComponent: lazyWithPreload(() => import('./BaseFeatureWidget/BaseFeatureDetail/index.js')),
             });
         });
     }

package/esm/PhasedScheduler.d.ts

@@ -1,7 +1,9 @@
+type Callback = () => void;
 export default class PhasedScheduler<PhaseName extends string> {
-    phaseCallbacks: Map<PhaseName, Function[]>;
+    phaseCallbacks: Map<PhaseName, Callback[]>;
     phaseOrder: PhaseName[];
     constructor(...phaseOrder: PhaseName[]);
-    add(phase: PhaseName, callback: Function): void;
+    add(phase: PhaseName, callback: Callback): void;
     run(): void;
 }
+export {};

package/esm/PhasedScheduler.js

@@ -1,3 +1,5 @@
+// helper class that keeps groups of callbacks that are then run in a specified
+// order by group
 export default class PhasedScheduler {
     phaseCallbacks = new Map();
     phaseOrder = [];
@@ -16,10 +18,24 @@ export default class PhasedScheduler {
         phaseCallbacks.push(callback);
     }
     run() {
+        const errors = [];
         for (const phaseName of this.phaseOrder) {
-            for (const callback of this.phaseCallbacks.get(phaseName) || []) {
-                callback();
+            for (const callback of this.phaseCallbacks.get(phaseName) ?? []) {
+                try {
+                    callback();
+                }
+                catch (e) {
+                    errors.push(e);
+                }
             }
         }
+        this.phaseCallbacks.clear();
+        if (errors.length) {
+            // AggregateError's message names none of its causes, and plenty of
+            // surfaces print only `${error}` (the desktop start-screen snackbar, a
+            // console log), so a bare summary loses which plugin actually failed.
+            // formatErrorStack walks .errors for the full stacks.
+            throw new AggregateError(errors, `Errors during pluggable element creation: ${errors.map(e => `${e}`).join('; ')}`);
+        }
     }
 }

package/esm/Plugin.d.ts

@@ -1,13 +1,18 @@
 import type PluginManager from './PluginManager.ts';
 import type { AnyConfigurationSchemaType } from './configuration/index.ts';
+import type { IAnyType } from '@jbrowse/mobx-state-tree';
+/**
+ * base class for a JBrowse plugin
+ */
 export default abstract class Plugin {
     abstract name: string;
     url?: string;
     version?: string;
     install(_pluginManager: PluginManager): void;
     configure(_pluginManager: PluginManager): void;
+    uninstall(_pluginManager: PluginManager): void;
     configurationSchema?: AnyConfigurationSchemaType;
     configurationSchemaUnnamespaced?: AnyConfigurationSchemaType;
-    rootConfigurationSchema?: (arg: PluginManager) => Record<string, AnyConfigurationSchemaType>;
+    rootConfigurationSchema?: (arg: PluginManager) => Record<string, AnyConfigurationSchemaType | IAnyType>;
 }
 export type PluginConstructor = new (...args: unknown[]) => Plugin;

package/esm/Plugin.js

@@ -1,9 +1,16 @@
+/**
+ * base class for a JBrowse plugin
+ */
 export default class Plugin {
     url;
     version;
     install(_pluginManager) { }
     configure(_pluginManager) { }
+    uninstall(_pluginManager) { }
+    // this is put into configuration.YourPluginName.configSlot
     configurationSchema;
+    // this is put into configuration.configSlot
     configurationSchemaUnnamespaced;
+    // this is spread into the root config, just configSlot
     rootConfigurationSchema;
 }