@jbrowse/core 4.3.0 → 5.0.0-beta.10

package/esm/pluggableElementTypes/models/baseTrackConfig.d.ts

@@ -1,87 +1,164 @@
 import type PluginManager from '../../PluginManager.ts';
+import type { LegacyDisplaySnapshot } from './migrateTrackConfig.ts';
 import type { Instance } from '@jbrowse/mobx-state-tree';
-export declare function createBaseTrackConfig(pluginManager: PluginManager): import("../../configuration/configurationSchema.ts").ConfigurationSchemaType<{
-    name: {
-        description: string;
-        type: string;
-        defaultValue: string;
+interface TrackConfigSnapshot {
+    trackId: string;
+    name: string;
+    type: string;
+    assemblyNames?: unknown;
+    textSearching?: {
+        textSearchAdapter?: unknown;
     };
-    assemblyNames: {
-        description: string;
-        type: string;
-        defaultValue: string[];
+    adapter?: {
+        type?: unknown;
     };
-    description: {
-        description: string;
+    displays?: LegacyDisplaySnapshot[];
+}
+/**
+ * Whether a track's adapter serves what a display type draws from: every
+ * `adapterCapabilities` entry the display asks for, among those the adapter
+ * type declares.
+ */
+export declare function adapterFeeds(pluginManager: PluginManager, adapter: TrackConfigSnapshot['adapter']): (display: {
+    adapterCapabilities: readonly string[];
+}) => boolean;
+/**
+ * The display types of `trackType` a track on `adapter` can draw as, in the
+ * track type's order.
+ */
+export declare function displayTypesFedBy(pluginManager: PluginManager, trackType: string, adapter: TrackConfigSnapshot['adapter']): string[];
+/**
+ * The display types a view may open a track as, best first: those its adapter
+ * feeds, the ones its config declares leading in declared order. A declared
+ * display the adapter cannot feed stays in the config as settings and is never
+ * a candidate.
+ */
+export declare function displayCandidates(pluginManager: PluginManager, track: {
+    type: string;
+    adapter?: TrackConfigSnapshot['adapter'];
+    displays?: readonly {
         type: string;
-        defaultValue: string;
+    }[];
+}): string[];
+/**
+ * Snapshot normalization shared by every track config schema (including
+ * ReferenceSequenceTrack). Loads retired display types as the displays they
+ * retired into, runs the `Core-preProcessTrackConfig` extension point,
+ * auto-fills a stub display for each of the track type's registered displays
+ * whose adapter capabilities the track's adapter declares, folds the
+ * `displayDefaults` shorthand into those entries, dedupes by type (first wins),
+ * and lifts legacy renderer configs.
+ */
+export declare function preprocessTrackConfigSnapshot(pluginManager: PluginManager, snapshot: Record<string, unknown>): {
+    trackId: string;
+    name: string;
+    type: string;
+    assemblyNames?: unknown;
+    textSearching?: {
+        textSearchAdapter?: unknown;
     };
-    category: {
-        description: string;
-        type: string;
-        defaultValue: never[];
+    adapter?: {
+        type?: unknown;
     };
-    metadata: {
+    displays: {
         type: string;
-        description: string;
-        defaultValue: {};
+        featureHeight?: {} | null | undefined;
+        displayId: string;
+    }[];
+};
+/**
+ * #config BaseTrack
+ * Configuration shared by all track types. Concrete tracks (FeatureTrack,
+ * AlignmentsTrack, VariantTrack, ...) extend this, so every track accepts these
+ * fields in addition to its own.
+ */
+export declare function createBaseTrackConfig(pluginManager: PluginManager): import("../../configuration/configurationSchema.ts").ConfigurationSchemaType<{
+    readonly name: {
+        type: "string";
+    } & {
+        defaultValue: string;
     };
-    rpcDriverName: {
-        type: string;
-        description: string;
+    readonly assemblyNames: {
+        type: "stringArray";
+    } & {
+        defaultValue: unknown;
+    };
+    readonly description: {
+        type: "string";
+    } & {
         defaultValue: string;
     };
-    adapter: import("@jbrowse/mobx-state-tree").IAnyModelType;
-    textSearching: import("../../configuration/configurationSchema.ts").ConfigurationSchemaType<{
-        indexingAttributes: {
-            type: string;
-            description: string;
-            defaultValue: string[];
+    readonly category: {
+        type: "stringArray";
+    } & {
+        defaultValue: unknown;
+    };
+    readonly metadata: {
+        type: "frozen";
+    } & {
+        defaultValue: unknown;
+    };
+    readonly adapter: import("@jbrowse/core/PluginManager").PluggableConfigSchemaType;
+    readonly textSearching: import("../../configuration/configurationSchema.ts").ConfigurationSchemaType<{
+        readonly indexingAttributes: {
+            type: "stringArray";
+        } & {
+            defaultValue: unknown;
+        };
+        readonly indexingFeatureTypesToExclude: {
+            type: "stringArray";
+        } & {
+            defaultValue: unknown;
         };
-        indexingFeatureTypesToExclude: {
-            type: string;
-            description: string;
-            defaultValue: string[];
+        readonly indexingFeatureTypesToInclude: {
+            type: "stringArray";
+        } & {
+            defaultValue: unknown;
         };
-        textSearchAdapter: import("@jbrowse/mobx-state-tree").IAnyModelType;
-    }, import("../../configuration/configurationSchema.ts").ConfigurationSchemaOptions<undefined, undefined>>;
-    displays: import("@jbrowse/mobx-state-tree").IArrayType<import("@jbrowse/mobx-state-tree").IAnyModelType>;
-    formatDetails: import("../../configuration/configurationSchema.ts").ConfigurationSchemaType<{
-        feature: {
-            type: string;
-            description: string;
-            defaultValue: {};
-            contextVariable: string[];
+        readonly textSearchAdapter: import("@jbrowse/mobx-state-tree").ITypeUnion<any, any, import("../../configuration/types.ts").PluggableConfigNode | undefined>;
+    }, import("../../configuration/configurationSchema.ts").ConfigurationSchemaOptions<undefined, undefined, undefined, import("../../configuration/requirements.ts").ConfigurationSchemaRequirement<Partial<Record<string, string[]>>, string>, any>>;
+    readonly displays: import("@jbrowse/mobx-state-tree").IArrayType<import("@jbrowse/core/PluginManager").PluggableConfigSchemaType>;
+    readonly formatDetails: import("../../configuration/configurationSchema.ts").ConfigurationSchemaType<{
+        readonly feature: {
+            type: "frozen";
+        } & {
+            defaultValue: unknown;
         };
-        subfeatures: {
-            type: string;
-            description: string;
-            defaultValue: {};
-            contextVariable: string[];
+        readonly subfeatures: {
+            type: "frozen";
+        } & {
+            defaultValue: unknown;
         };
-        depth: {
-            type: string;
-            defaultValue: number;
-            description: string;
+        readonly depth: {
+            type: "maybeNumber";
         };
-        maxDepth: {
-            type: string;
-            defaultValue: number;
-            description: string;
+        readonly maxDepth: {
+            type: "maybeNumber";
         };
-    }, import("../../configuration/configurationSchema.ts").ConfigurationSchemaOptions<undefined, undefined>>;
-    formatAbout: import("../../configuration/configurationSchema.ts").ConfigurationSchemaType<{
-        config: {
-            type: string;
-            description: string;
-            defaultValue: {};
-            contextVariable: string[];
+    }, import("../../configuration/configurationSchema.ts").ConfigurationSchemaOptions<undefined, undefined, undefined, import("../../configuration/requirements.ts").ConfigurationSchemaRequirement<Partial<Record<string, string[]>>, string>, any>>;
+    readonly formatAbout: import("../../configuration/configurationSchema.ts").ConfigurationSchemaType<{
+        readonly config: {
+            type: "frozen";
+        } & {
+            defaultValue: unknown;
         };
-        hideUris: {
-            type: string;
+        readonly hideUris: {
+            type: "boolean";
+        } & {
             defaultValue: boolean;
         };
-    }, import("../../configuration/configurationSchema.ts").ConfigurationSchemaOptions<undefined, undefined>>;
-}, import("../../configuration/configurationSchema.ts").ConfigurationSchemaOptions<undefined, "trackId">>;
+    }, import("../../configuration/configurationSchema.ts").ConfigurationSchemaOptions<undefined, undefined, undefined, import("../../configuration/requirements.ts").ConfigurationSchemaRequirement<Partial<Record<string, string[]>>, string>, any>>;
+    type: {
+        type: "string";
+    } & {
+        defaultValue: string;
+    };
+    trackId: {
+        type: "string";
+    } & {
+        defaultValue: string;
+    };
+}, import("../../configuration/configurationSchema.ts").ConfigurationSchemaOptions<undefined, "trackId", true, import("../../configuration/requirements.ts").ConfigurationSchemaRequirement<Partial<Record<string, string[]>>, string>, any>>;
 export type BaseTrackConfigSchema = ReturnType<typeof createBaseTrackConfig>;
 export type BaseTrackConfig = Instance<BaseTrackConfigSchema>;
+export {};

package/esm/pluggableElementTypes/models/baseTrackConfig.js

@@ -1,134 +1,259 @@
 import { types } from '@jbrowse/mobx-state-tree';
-import { ConfigurationSchema } from "../../configuration/index.js";
+import { ConfigurationSchema, FormatAboutConfigSchemaFactory, FormatDetailsConfigSchemaFactory, } from '../../configuration/index.js';
+import { expandLooseSearchIndex } from '../../util/expandLooseSearchIndex.js';
+import { expandTrackConfigShorthand } from './expandTrackConfigShorthand.js';
+import { liftLegacyRendererConfig, migrateRetiredDisplays, } from './migrateTrackConfig.js';
+/**
+ * Whether a track's adapter serves what a display type draws from: every
+ * `adapterCapabilities` entry the display asks for, among those the adapter
+ * type declares.
+ */
+export function adapterFeeds(pluginManager, adapter) {
+    const type = adapter?.type;
+    const capabilities = new Set(typeof type === 'string' && pluginManager.hasAdapterType(type)
+        ? pluginManager.getAdapterType(type).adapterCapabilities
+        : []);
+    return (display) => display.adapterCapabilities.every(c => capabilities.has(c));
+}
+/**
+ * The display types of `trackType` a track on `adapter` can draw as, in the
+ * track type's order.
+ */
+export function displayTypesFedBy(pluginManager, trackType, adapter) {
+    return pluginManager
+        .getTrackType(trackType)
+        .displayTypes.filter(adapterFeeds(pluginManager, adapter))
+        .map(d => d.name);
+}
+/**
+ * The display types a view may open a track as, best first: those its adapter
+ * feeds, the ones its config declares leading in declared order. A declared
+ * display the adapter cannot feed stays in the config as settings and is never
+ * a candidate.
+ */
+export function displayCandidates(pluginManager, track) {
+    const declared = (track.displays ?? []).map(d => pluginManager.resolveDisplayTypeRecord(d.type)?.name ?? d.type);
+    const rank = (name) => {
+        const i = declared.indexOf(name);
+        return i === -1 ? declared.length : i;
+    };
+    return displayTypesFedBy(pluginManager, track.type, track.adapter).sort((a, b) => rank(a) - rank(b));
+}
+/**
+ * Snapshot normalization shared by every track config schema (including
+ * ReferenceSequenceTrack). Loads retired display types as the displays they
+ * retired into, runs the `Core-preProcessTrackConfig` extension point,
+ * auto-fills a stub display for each of the track type's registered displays
+ * whose adapter capabilities the track's adapter declares, folds the
+ * `displayDefaults` shorthand into those entries, dedupes by type (first wins),
+ * and lifts legacy renderer configs.
+ */
+export function preprocessTrackConfigSnapshot(pluginManager, snapshot) {
+    const pre = pluginManager.evaluateExtensionPoint(
+    /** #extensionPoint Core-preProcessTrackConfig | sync | Rewrite a track config snapshot before it is instantiated */
+    'Core-preProcessTrackConfig', migrateRetiredDisplays(pluginManager, structuredClone(snapshot)));
+    // a non-array `displays` would crash MST union-type probing
+    const declared = Array.isArray(pre.displays) ? pre.displays : [];
+    let displays = declared;
+    if (pre.trackId !== 'placeholderId') {
+        // The displays the config declared lead, in its order; every other one
+        // the adapter feeds follows in the track type's own order.
+        try {
+            const declaredTypes = new Set(declared.map(d => d.type));
+            const feeds = adapterFeeds(pluginManager, pre.adapter);
+            displays = [
+                ...declared,
+                ...pluginManager
+                    .getTrackType(pre.type ?? '')
+                    .displayTypes.filter(d => !declaredTypes.has(d.name) && feeds(d))
+                    .map(d => ({ displayId: `${pre.trackId}-${d.name}`, type: d.name })),
+            ];
+        }
+        catch (e) {
+            throw new Error(`Unknown track type "${pre.type}" in ${JSON.stringify(pre)}`, { cause: e });
+        }
+    }
+    const snap = expandTrackConfigShorthand({ ...pre, displays }, pluginManager);
+    const knownDisplayTypes = new Set(pluginManager.getDisplayElements().map(d => d.name));
+    // one display per type; the first keeps its place as the default
+    const seenTypes = new Set();
+    const { textSearching } = snap;
+    return {
+        ...snap,
+        ...(textSearching?.textSearchAdapter
+            ? {
+                textSearching: {
+                    ...textSearching,
+                    textSearchAdapter: expandLooseSearchIndex(textSearching.textSearchAdapter, snap.assemblyNames),
+                },
+            }
+            : {}),
+        displays: snap.displays
+            .filter(d => {
+            const known = knownDisplayTypes.has(d.type);
+            if (!known) {
+                console.warn(`Dropping display of unknown type "${d.type}" from track "${snap.trackId}": no registered display type has that name`);
+            }
+            return known;
+        })
+            .filter(d => {
+            const dup = seenTypes.has(d.type);
+            seenTypes.add(d.type);
+            return !dup;
+        })
+            .map(d => liftLegacyRendererConfig(d, snap.trackId)),
+    };
+}
+/**
+ * #config BaseTrack
+ * Configuration shared by all track types. Concrete tracks (FeatureTrack,
+ * AlignmentsTrack, VariantTrack, ...) extend this, so every track accepts these
+ * fields in addition to its own.
+ */
 export function createBaseTrackConfig(pluginManager) {
+    const none = types.optional(types.undefined, undefined);
+    const adapter = pluginManager.pluggableConfigSchemaType('text search adapter');
+    // A dispatcher rather than `types.maybe` or member order. Every adapter here
+    // is all-default, so an omitted key has to resolve to nothing rather than the
+    // first registered adapter (textSearchAdapterSlotOmission.test.ts). And
+    // clearing a set slot, as undo does, must not hand `undefined` to the current
+    // adapter's preProcessSnapshot, which MST's own matching does to test it.
+    const optionalTextSearchAdapter = types.union({ dispatcher: snapshot => (snapshot === undefined ? none : adapter) }, none, adapter);
     return ConfigurationSchema('BaseTrack', {
+        /**
+         * #slot
+         */
         name: {
-            description: 'descriptive name of the track',
+            description: 'descriptive name of the track, falls back to the trackId when unset',
             type: 'string',
-            defaultValue: 'Track',
+            defaultValue: '',
         },
+        /**
+         * #slot
+         */
         assemblyNames: {
             description: 'name of the assembly (or assemblies) track belongs to',
             type: 'stringArray',
             defaultValue: ['assemblyName'],
         },
+        /**
+         * #slot
+         */
         description: {
             description: 'a description of the track',
             type: 'string',
             defaultValue: '',
         },
+        /**
+         * #slot
+         */
         category: {
             description: 'the category and sub-categories of a track',
             type: 'stringArray',
             defaultValue: [],
         },
+        /**
+         * #slot
+         */
         metadata: {
             type: 'frozen',
             description: 'anything to add about this track',
             defaultValue: {},
         },
-        rpcDriverName: {
-            type: 'string',
-            description: 'RPC driver to use for this track. Leave empty to use the display-level or global default.',
-            defaultValue: '',
-        },
+        /**
+         * #slot
+         * where this track's data comes from. Its `type` names the adapter for
+         * the file format (`BamAdapter`, `Gff3TabixAdapter`, ...) and the rest of
+         * the object is that adapter's own slots — see the adapter pages for
+         * each. Most adapters also accept a `uri` shorthand in place of writing
+         * their location slots out.
+         */
         adapter: pluginManager.pluggableConfigSchemaType('adapter'),
         textSearching: ConfigurationSchema('textSearching', {
+            /**
+             * #slot textSearching.indexingAttributes
+             */
             indexingAttributes: {
                 type: 'stringArray',
                 description: 'list of which feature attributes to index for text searching',
-                defaultValue: ['Name', 'ID'],
+                defaultValue: ['Name', 'ID', 'symbol'],
             },
+            /**
+             * #slot textSearching.indexingFeatureTypesToExclude
+             */
             indexingFeatureTypesToExclude: {
                 type: 'stringArray',
                 description: 'list of feature types to exclude in text search index',
                 defaultValue: ['CDS', 'exon'],
             },
-            textSearchAdapter: pluginManager.pluggableConfigSchemaType('text search adapter'),
-        }),
-        displays: types.array(pluginManager.pluggableConfigSchemaType('display')),
-        formatDetails: ConfigurationSchema('FormatDetails', {
-            feature: {
-                type: 'frozen',
-                description: 'adds extra fields to the feature details',
-                defaultValue: {},
-                contextVariable: ['feature'],
-            },
-            subfeatures: {
-                type: 'frozen',
-                description: 'adds extra fields to the subfeatures of a feature',
-                defaultValue: {},
-                contextVariable: ['feature'],
-            },
-            depth: {
-                type: 'number',
-                defaultValue: 2,
-                description: 'depth of subfeatures to iterate the formatter on formatDetails.subfeatures (e.g. you may not want to format the exon/cds subfeatures, so limited to 2',
-            },
-            maxDepth: {
-                type: 'number',
-                defaultValue: 99999,
-                description: 'Maximum depth to render subfeatures',
-            },
-        }),
-        formatAbout: ConfigurationSchema('FormatAbout', {
-            config: {
-                type: 'frozen',
-                description: 'formats configuration object in about dialog',
-                defaultValue: {},
-                contextVariable: ['config'],
-            },
-            hideUris: {
-                type: 'boolean',
-                defaultValue: false,
+            /**
+             * #slot textSearching.indexingFeatureTypesToInclude
+             * The only feature types to index, dropping every other type the file
+             * carries. Empty (the default) means no allow list, i.e. index
+             * everything `indexingFeatureTypesToExclude` does not name.
+             *
+             * Use this instead of the exclude list when the file draws from a
+             * vocabulary you do not control. An NCBI RefSeq GFF3 uses 115 feature
+             * types, 80 of them leaf records with nothing to search for — a `match`
+             * is labelled with a bare UUID, a `cDNA_match` with an MD5, every
+             * `biological_region` with the literal string "biological region" — so
+             * a deny list leaks whichever type is added next, while the allow list
+             * (gene, pseudogene, and the transcript types) does not grow. Both may
+             * be set: this one admits, the exclude list then narrows.
+             *
+             * GFF3 only; the GTF and VCF indexers do not filter by type.
+             */
+            indexingFeatureTypesToInclude: {
+                type: 'stringArray',
+                description: 'the only feature types to index; empty means index every type not excluded',
+                defaultValue: [],
             },
+            /**
+             * #slot textSearching.textSearchAdapter
+             * a per-track name search index, normally a `TrixTextSearchAdapter`
+             * over what `jbrowse text-index --tracks` built; `'genes.ix'` is
+             * enough, searching this track's assemblies. Without one, this
+             * track's features are only findable through an assembly-wide search
+             * adapter.
+             */
+            textSearchAdapter: optionalTextSearchAdapter,
         }),
+        /**
+         * #slot
+         * An **array** of full display configs, e.g.
+         * `displays: [{ type: 'LinearBasicDisplay', color: 'green' }]`. Each entry
+         * names a display `type`; use this when you need exact control — your own
+         * `displayId`, different settings for two displays, or choosing which
+         * display is the default.
+         *
+         * For the common case, prefer the `displayDefaults` shorthand instead — an
+         * object of appearance settings (e.g. `displayDefaults: { color: 'green' }`)
+         * that JBrowse routes to whichever display uses each setting, so you don't
+         * have to name the display or write the array.
+         *
+         * See the [track config guide](/docs/config_guides/tracks/#configuring-displays).
+         */
+        displays: types.array(pluginManager.pluggableConfigSchemaType('display')),
+        /**
+         * #slot
+         * jexl callbacks that add, rewrite or hide fields in this track's
+         * feature-details panel. The same schema exists session-wide as
+         * `configuration.formatDetails`.
+         */
+        formatDetails: FormatDetailsConfigSchemaFactory(),
+        /**
+         * #slot
+         * jexl callbacks that add, rewrite or hide fields in this track's About
+         * dialog. The same schema exists session-wide as
+         * `configuration.formatAbout`.
+         */
+        formatAbout: FormatAboutConfigSchemaFactory(),
     }, {
-        preProcessSnapshot: s2 => {
-            const snap = pluginManager.evaluateExtensionPoint('Core-preProcessTrackConfig', structuredClone(s2));
-            const { displays = [] } = snap;
-            if (snap.trackId !== 'placeholderId') {
-                try {
-                    const configDisplayTypes = new Set(displays.map(d => d.type));
-                    for (const d of pluginManager.getTrackType(snap.type)
-                        .displayTypes) {
-                        if (!configDisplayTypes.has(d.name)) {
-                            displays.push({
-                                displayId: `${snap.trackId}-${d.name}`,
-                                type: d.name,
-                            });
-                        }
-                    }
-                }
-                catch (e) {
-                    throw new Error(`Unknown track type "${snap.type}" in ${JSON.stringify(snap)}`, {
-                        cause: e,
-                    });
-                }
-            }
-            return {
-                ...snap,
-                displays: displays.map(d => ({
-                    ...d,
-                    displayId: d.displayId ?? `${snap.trackId}-${d.type}`,
-                })),
-            };
-        },
+        preProcessSnapshot: s2 => preprocessTrackConfigSnapshot(pluginManager, s2),
+        /**
+         * #identifier
+         */
         explicitIdentifier: 'trackId',
         explicitlyTyped: true,
-        actions: (self) => ({
-            addDisplayConf(conf) {
-                const { type } = conf;
-                if (!type) {
-                    throw new Error(`unknown display type ${type}`);
-                }
-                const display = self.displays.find((d) => d?.displayId === conf.displayId);
-                if (display) {
-                    return display;
-                }
-                const length = self.displays.push(conf);
-                return self.displays[length - 1];
-            },
-        }),
     });
 }

package/esm/pluggableElementTypes/models/components/SaveTrackData.d.ts

@@ -1,11 +1,6 @@
-import type { AnyConfigurationModel } from '../../../configuration/index.ts';
-import type { FileTypeExporter } from '../saveTrackFileTypes/types.ts';
-import type { IAnyStateTreeNode } from '@jbrowse/mobx-state-tree';
+import type { ExportableTrack } from './fetchTrackData.ts';
 declare const SaveTrackDataDialog: ({ model, handleClose, }: {
-    model: IAnyStateTreeNode & {
-        configuration: AnyConfigurationModel;
-        saveTrackFileFormatOptions: () => Record<string, FileTypeExporter>;
-    };
+    model: ExportableTrack;
     handleClose: () => void;
-}) => import("react/jsx-runtime").JSX.Element;
+}) => import("react").JSX.Element;
 export default SaveTrackDataDialog;