@jbrowse/core 4.3.0 → 5.0.0-beta.1

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

@@ -1,87 +1,203 @@
 import type PluginManager from '../../PluginManager.ts';
 import type { Instance } from '@jbrowse/mobx-state-tree';
-export declare function createBaseTrackConfig(pluginManager: PluginManager): import("../../configuration/configurationSchema.ts").ConfigurationSchemaType<{
-    name: {
-        description: string;
+/**
+ * Snapshot normalization shared by every track config schema (including
+ * ReferenceSequenceTrack). Runs the `Core-preProcessTrackConfig` extension
+ * point, expands the `displayDefaults` shorthand, auto-fills a stub display for
+ * each of the track type's registered displays, normalizes legacy display-type
+ * aliases to their canonical name, 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;
+    displays: {
         type: string;
-        defaultValue: string;
+        featureHeight?: {} | null | undefined;
+        displayId: string;
+    }[];
+};
+/**
+ * The `addDisplayConf` action shared by every track config schema — appends a
+ * display config unless one with the same displayId already exists.
+ */
+interface DisplayConf {
+    type: string;
+    displayId: string;
+}
+export declare function trackConfigActions(self: unknown): {
+    addDisplayConf(conf: DisplayConf): DisplayConf | undefined;
+};
+/**
+ * #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<{
+    /**
+     * #slot
+     */
+    readonly name: {
+        readonly description: "descriptive name of the track, falls back to the trackId when unset";
+        readonly type: "string";
+        readonly defaultValue: "";
     };
-    assemblyNames: {
-        description: string;
-        type: string;
-        defaultValue: string[];
+    /**
+     * #slot
+     */
+    readonly assemblyNames: {
+        readonly description: "name of the assembly (or assemblies) track belongs to";
+        readonly type: "stringArray";
+        readonly defaultValue: readonly ["assemblyName"];
     };
-    description: {
-        description: string;
-        type: string;
-        defaultValue: string;
+    /**
+     * #slot
+     */
+    readonly description: {
+        readonly description: "a description of the track";
+        readonly type: "string";
+        readonly defaultValue: "";
     };
-    category: {
-        description: string;
-        type: string;
-        defaultValue: never[];
+    /**
+     * #slot
+     */
+    readonly category: {
+        readonly description: "the category and sub-categories of a track";
+        readonly type: "stringArray";
+        readonly defaultValue: readonly [];
     };
-    metadata: {
-        type: string;
-        description: string;
-        defaultValue: {};
-    };
-    rpcDriverName: {
-        type: string;
-        description: string;
-        defaultValue: string;
+    /**
+     * #slot
+     */
+    readonly metadata: {
+        readonly type: "frozen";
+        readonly description: "anything to add about this track";
+        readonly defaultValue: {};
     };
-    adapter: import("@jbrowse/mobx-state-tree").IAnyModelType;
-    textSearching: import("../../configuration/configurationSchema.ts").ConfigurationSchemaType<{
-        indexingAttributes: {
-            type: string;
-            description: string;
-            defaultValue: string[];
+    /**
+     * #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.
+     */
+    readonly adapter: import("@jbrowse/mobx-state-tree").IAnyType;
+    readonly textSearching: import("../../configuration/configurationSchema.ts").ConfigurationSchemaType<{
+        /**
+         * #slot textSearching.indexingAttributes
+         */
+        readonly indexingAttributes: {
+            readonly type: "stringArray";
+            readonly description: "list of which feature attributes to index for text searching";
+            readonly defaultValue: readonly ["Name", "ID", "symbol"];
+        };
+        /**
+         * #slot textSearching.indexingFeatureTypesToExclude
+         */
+        readonly indexingFeatureTypesToExclude: {
+            readonly type: "stringArray";
+            readonly description: "list of feature types to exclude in text search index";
+            readonly defaultValue: readonly ["CDS", "exon"];
         };
-        indexingFeatureTypesToExclude: {
-            type: string;
-            description: string;
-            defaultValue: string[];
+        /**
+         * #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.
+         */
+        readonly indexingFeatureTypesToInclude: {
+            readonly type: "stringArray";
+            readonly description: "the only feature types to index; empty means index every type not excluded";
+            readonly defaultValue: readonly [];
         };
-        textSearchAdapter: import("@jbrowse/mobx-state-tree").IAnyModelType;
+        /**
+         * #slot textSearching.textSearchAdapter
+         * a per-track name search index, normally a `TrixTextSearchAdapter`
+         * over what `jbrowse text-index --tracks` built. Without one, this
+         * track's features are only findable through an assembly-wide search
+         * adapter.
+         */
+        readonly textSearchAdapter: import("@jbrowse/mobx-state-tree").IAnyType;
     }, 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[];
+    /**
+     * #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).
+     */
+    readonly displays: import("@jbrowse/mobx-state-tree").IArrayType<import("@jbrowse/mobx-state-tree").IAnyType>;
+    /**
+     * #slot
+     * jexl callbacks that add, rewrite or hide fields in this track's
+     * feature-details panel. Four slots, listed at
+     * [FormatDetails](/docs/config/formatdetails), and the same schema exists
+     * session-wide as `configuration.formatDetails`.
+     */
+    readonly formatDetails: import("../../configuration/configurationSchema.ts").ConfigurationSchemaType<{
+        readonly feature: {
+            readonly type: "frozen";
+            readonly description: "adds extra fields to the feature details";
+            readonly defaultValue: {};
+            readonly contextVariable: ["feature"];
         };
-        subfeatures: {
-            type: string;
-            description: string;
-            defaultValue: {};
-            contextVariable: string[];
+        readonly subfeatures: {
+            readonly type: "frozen";
+            readonly description: "adds extra fields to the subfeatures of a feature";
+            readonly defaultValue: {};
+            readonly contextVariable: ["feature"];
         };
-        depth: {
-            type: string;
-            defaultValue: number;
-            description: string;
+        readonly depth: {
+            readonly type: "maybeNumber";
+            readonly description: "levels of subfeature the formatDetails.subfeatures callback runs on, default 2";
         };
-        maxDepth: {
-            type: string;
-            defaultValue: number;
-            description: string;
+        readonly maxDepth: {
+            readonly type: "maybeNumber";
+            readonly description: "hide subfeatures nested deeper than this, default no limit";
         };
     }, import("../../configuration/configurationSchema.ts").ConfigurationSchemaOptions<undefined, undefined>>;
-    formatAbout: import("../../configuration/configurationSchema.ts").ConfigurationSchemaType<{
-        config: {
-            type: string;
-            description: string;
-            defaultValue: {};
-            contextVariable: string[];
+    /**
+     * #slot
+     * jexl callbacks that add, rewrite or hide fields in this track's About
+     * dialog. Two slots, listed at
+     * [FormatAbout](/docs/config/formatabout), and the same schema exists
+     * session-wide as `configuration.formatAbout`.
+     */
+    readonly formatAbout: import("../../configuration/configurationSchema.ts").ConfigurationSchemaType<{
+        readonly config: {
+            readonly type: "frozen";
+            readonly description: "formats configuration object in about dialog";
+            readonly defaultValue: {};
+            readonly contextVariable: ["config"];
         };
-        hideUris: {
-            type: string;
-            defaultValue: boolean;
+        readonly hideUris: {
+            readonly type: "boolean";
+            readonly defaultValue: false;
         };
     }, import("../../configuration/configurationSchema.ts").ConfigurationSchemaOptions<undefined, undefined>>;
 }, import("../../configuration/configurationSchema.ts").ConfigurationSchemaOptions<undefined, "trackId">>;
 export type BaseTrackConfigSchema = ReturnType<typeof createBaseTrackConfig>;
 export type BaseTrackConfig = Instance<BaseTrackConfigSchema>;
+export {};

package/esm/pluggableElementTypes/models/baseTrackConfig.js

@@ -1,134 +1,236 @@
 import { types } from '@jbrowse/mobx-state-tree';
-import { ConfigurationSchema } from "../../configuration/index.js";
+import { ConfigurationSchema, FormatAboutConfigSchemaFactory, FormatDetailsConfigSchemaFactory, } from '../../configuration/index.js';
+import { expandTrackConfigShorthand } from './expandTrackConfigShorthand.js';
+import { liftLegacyRendererConfig } from './migrateTrackConfig.js';
+/**
+ * Snapshot normalization shared by every track config schema (including
+ * ReferenceSequenceTrack). Runs the `Core-preProcessTrackConfig` extension
+ * point, expands the `displayDefaults` shorthand, auto-fills a stub display for
+ * each of the track type's registered displays, normalizes legacy display-type
+ * aliases to their canonical name, dedupes by type (first wins), and lifts
+ * legacy renderer configs.
+ */
+export function preprocessTrackConfigSnapshot(pluginManager, snapshot) {
+    const snap = expandTrackConfigShorthand(pluginManager.evaluateExtensionPoint(
+    /** #extensionPoint Core-preProcessTrackConfig | sync | Rewrite a track config snapshot before it is instantiated */
+    'Core-preProcessTrackConfig', structuredClone(snapshot)), pluginManager);
+    // expandTrackConfigShorthand folds any `displayDefaults` shorthand into
+    // `displays`, but its early-return branches can leave a malformed `displays`
+    // untouched; guard so MST union-type probing never crashes on a non-array
+    // `displays`.
+    const displays = Array.isArray(snap.displays) ? snap.displays : [];
+    if (snap.trackId !== 'placeholderId') {
+        // Add any of the track type's possible displays not already on the snapshot
+        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 });
+        }
+    }
+    const displayElements = pluginManager.getDisplayElements();
+    const knownDisplayTypes = new Set(displayElements.map(d => d.name));
+    // Map of legacy display type → canonical name, built from each DisplayType's
+    // `aliases` declaration. Lets each display "own" its renames without a central
+    // migration file.
+    const displayAliasMap = new Map();
+    for (const d of displayElements) {
+        if (d.aliases) {
+            for (const alias of d.aliases) {
+                displayAliasMap.set(alias, d.name);
+            }
+        }
+    }
+    // After alias normalization, dedupe by type so the track config holds one
+    // display per type (old sessions can carry several display configs whose types
+    // are all aliases of one canonical type). First occurrence wins to preserve
+    // the default (displays[0]).
+    const seenTypes = new Set();
+    return {
+        ...snap,
+        displays: displays
+            .map(d => {
+            const canonical = displayAliasMap.get(d.type);
+            return canonical ? { ...d, type: canonical } : d;
+        })
+            .filter(d => knownDisplayTypes.has(d.type))
+            .filter(d => {
+            const dup = seenTypes.has(d.type);
+            seenTypes.add(d.type);
+            return !dup;
+        })
+            .map(d => liftLegacyRendererConfig(d, snap.trackId)),
+    };
+}
+export function trackConfigActions(self) {
+    const { displays } = self;
+    return {
+        addDisplayConf(conf) {
+            const { type } = conf;
+            if (!type) {
+                throw new Error('display type not specified');
+            }
+            const display = displays.find(d => d.displayId === conf.displayId);
+            if (display) {
+                return display;
+            }
+            const length = displays.push(conf);
+            return displays[length - 1];
+        },
+    };
+}
+/**
+ * #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) {
     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'],
             },
+            /**
+             * #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. Without one, this
+             * track's features are only findable through an assembly-wide search
+             * adapter.
+             */
             textSearchAdapter: pluginManager.pluggableConfigSchemaType('text search adapter'),
         }),
+        /**
+         * #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')),
-        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
+         * jexl callbacks that add, rewrite or hide fields in this track's
+         * feature-details panel. Four slots, listed at
+         * [FormatDetails](/docs/config/formatdetails), and 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. Two slots, listed at
+         * [FormatAbout](/docs/config/formatabout), and 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];
-            },
-        }),
+        actions: trackConfigActions,
     });
 }

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;