@jbrowse/core 5.0.0-beta.1 → 5.0.0-beta.11

package/esm/util/tracks.d.ts

@@ -1,8 +1,12 @@
 export { getFileName } from './getFileName.ts';
 export { getRpcSessionId } from './parentWalk.ts';
+export { makeIndex } from './formatGuessers.ts';
+export { isLooseTrackConfig, type LooseTrackInput, } from '@jbrowse/add-track-core';
+import { type LooseTrackInput } from '@jbrowse/add-track-core';
 import type PluginManager from '../PluginManager.ts';
 import type { AnyConfigurationModel } from '../configuration/index.ts';
 import type { BlobLocation, FileHandleLocation, FileLocation, PreFileLocation } from './types/data.ts';
+import type { AbstractViewContainer } from './types/index.ts';
 import type { IAnyStateTreeNode, IAnyType, IStateTreeNode, Instance, types } from '@jbrowse/mobx-state-tree';
 export declare function getTrackAssemblyNames(track: IStateTreeNode & {
     configuration: AnyConfigurationModel;
@@ -24,7 +28,7 @@ export interface AssemblyNameResolver {
  * which is built from assembly *models*, so it answers no during the window
  * where a config exists and the manager's afterAttach autorun hasn't built its
  * model yet — which is exactly when an import form first renders. `has` also
- * consults `assemblyNamesList`, read off the configs, so it covers both. See
+ * consults `confByName`, read off the configs, so it covers both. See
  * assemblyManager's own note on the pair.
  */
 export interface SessionAssemblies extends AssemblyNameResolver {
@@ -77,6 +81,13 @@ export declare function getConfAssemblyNames(conf: AnyConfigurationModel): strin
  * how to name.
  */
 export declare function getConfAssemblyNamesOrNone(conf: AnyConfigurationModel): string[];
+/**
+ * The RPC session id a track's own requests go out under, from its config:
+ * what `BaseTrackModel.rpcSessionId` computes, for a caller holding no model.
+ * A call under any other id lands on another worker, which builds a second
+ * copy of the adapter that nothing frees.
+ */
+export declare function getConfRpcSessionId(conf: AnyConfigurationModel): string;
 export declare const UNKNOWN = "UNKNOWN";
 export declare const UNSUPPORTED = "UNSUPPORTED";
 export declare function getBlob(id: string): File | undefined;
@@ -124,23 +135,6 @@ export declare function restoreFileHandlesFromSnapshot(sessionSnapshot: unknown,
     success: false;
     error: unknown;
 })[]>;
-/**
- * creates a new location from the provided location including the appropriate
- * suffix and location type
- *
- * @param location - the FileLocation
- * @param suffix - the file suffix (e.g. .bam)
- * @returns the constructed location object from the provided parameters
- */
-export declare function makeIndex(location: FileLocation, suffix: string): BlobLocation | FileHandleLocation | {
-    uri: string;
-    locationType: string;
-    baseUri?: string | undefined;
-    localPath?: undefined;
-} | {
-    localPath: string;
-    locationType: string;
-};
 /**
  * constructs a potential index file (with suffix) from the provided file name
  *
@@ -219,11 +213,6 @@ export declare function addTrackTypeGuesser(pluginManager: PluginManager, guess:
 export declare function stripFileExtension(name: string): string;
 export declare function guessAdapter(file: FileLocation, index: FileLocation | undefined, adapterHint?: string, model?: IAnyStateTreeNode): AdapterConfig;
 export declare function guessTrackType(adapterType: string, model?: IAnyStateTreeNode, file?: FileLocation): string;
-export interface LooseTrackInput {
-    uri: string;
-    index?: string;
-    [key: string]: unknown;
-}
 /**
  * Expand a loose track description — a bare data-file URI, or an object with
  * `uri` (and optional `index`) plus any extra config keys — into a full track
@@ -243,11 +232,21 @@ export declare function guessTrackConf(input: string | LooseTrackInput, pluginMa
     adapter: AdapterConfig;
 };
 /**
- * Whether a track snapshot is the loose `{ uri, ... }` form — a data file with
- * no `adapter` — that {@link expandLooseTrackConfig} expands.
+ * {@link guessTrackConf} over an already-built {@link FileLocation}, for a
+ * caller holding a location the loose `{ uri }` vocabulary cannot spell — a
+ * desktop local path. Kept separate so `LooseTrackInput` stays URI-only: it
+ * sits on the track-config union and the root config's `tracks`, where a
+ * local path would be a config a web deployment could not open.
+ *
+ * The `trackId` is a content hash of the adapter, not a timestamp, so adding
+ * the same file twice is idempotent — `addToSession` dedupes on it.
  */
-export declare function isLooseTrackConfig(snap: unknown): snap is LooseTrackInput & {
-    trackId?: string;
+export declare function guessTrackConfForLocation(file: FileLocation, index: FileLocation | undefined, pluginManager: PluginManager, assemblyName?: string): {
+    trackId: string;
+    type: string;
+    name: string;
+    assemblyNames: string[];
+    adapter: AdapterConfig;
 };
 /**
  * Expand a loose track config into a full one and leave any other snapshot
@@ -294,6 +293,7 @@ interface MinimalTrack extends IAnyType {
 interface GenericView {
     type: string;
     tracks: MSTArray<MinimalTrack>;
+    showTrack?: (trackId: string, initialSnapshot?: object, displayInitialSnapshot?: DisplayInitialSnapshot, inlineConf?: Record<string, unknown>) => unknown;
 }
 /**
  * The display-snapshot argument of `showTrackGeneric`, exported so a view's own
@@ -311,27 +311,6 @@ interface DisplayConfSnapshot {
     type: string;
     displayId?: string;
 }
-/**
- * Which display a track opens with in a given view, and the display config that
- * display must use: `{ type, conf }`, or undefined when the view supports none
- * of the track's displays.
- *
- * Two decisions, in this order, and the order is the point. The **type** is what
- * the caller asked for, else the track's first declared display the view
- * supports, else the track type's first supported display. The **config** is
- * then whichever declared entry has that type — never "the first supported one",
- * which is what let a display be created wearing another display's config node
- * (a multi-sample VCF declares both the matrix and the regular display, so the
- * regular one inherited the matrix's 20px connector-line zone and drew its
- * clustering tree offset from the rows it labels). `display.type ===
- * display.configuration.type` is the invariant `DisplayConfigurationReference`
- * already assumes when it falls back to resolving a display config by type; this
- * is where it has to hold.
- *
- * `conf` is undefined when the track config declares no entry of that type;
- * `baseTrackConfig.preProcessSnapshot` injects one for every registered display
- * type, so the caller's `${trackId}-${type}` id resolves to it.
- */
 /**
  * The display type names a view can render, as a lookup set. Built once per
  * view and handed to {@link viewCanDisplayTrack} for every track, rather than
@@ -339,17 +318,10 @@ interface DisplayConfSnapshot {
  */
 export declare function viewDisplayNames(pluginManager: PluginManager, viewType: string): Set<string>;
 /**
- * Whether a view rendering `viewDisplays` can open a track of this type at all
- * — does the track type declare a display the view draws. The coarse half of
- * the question {@link pickDisplayForView} answers precisely: a picker that
- * offers a track this says no to is offering one `showTrackGeneric` will
- * refuse.
- *
- * Reads the *track type's* registered displays rather than a config's own
- * `displays` array, which is both cheaper and the only form available on an
- * un-hydrated frozen track config (ADR-032). The two agree, since
- * `preprocessTrackConfigSnapshot` injects a stub display for every display the
- * track type registers.
+ * Whether a view rendering `viewDisplays` can open a track at all: does the
+ * track's adapter feed a display the view draws. The coarse half of the
+ * question {@link pickDisplayForView} answers precisely, over the same
+ * candidates, so a picker never offers a track `showTrackGeneric` will refuse.
  *
  * Two answers that are easy to get wrong, and both have been:
  *
@@ -363,12 +335,62 @@ export declare function viewDisplayNames(pluginManager: PluginManager, viewType:
  *   every track passes. That is a policy rather than a fact, and it lives here
  *   so the pickers agree on it.
  */
-export declare function viewCanDisplayTrack(pluginManager: PluginManager, viewDisplays: Set<string>, trackType: string): boolean;
-export declare function pickDisplayForView({ declaredDisplays, requestedType, trackDisplayTypes, viewDisplayTypes, }: {
+export declare function viewCanDisplayTrack(pluginManager: PluginManager, viewDisplays: Set<string>, track: {
+    type: string;
+    adapter?: {
+        type?: unknown;
+    };
+}): boolean;
+/**
+ * The tracks a view can be offered: those that support every assembly it
+ * displays, and that declare a display it can draw. The track selector's tree
+ * and every other picker that opens a track into a view read this one answer,
+ * or one of them offers a track the next hides.
+ */
+export declare function filterTracks(tracks: AnyConfigurationModel[], self: {
+    view?: IStateTreeNode & {
+        type: string;
+    };
+    assemblyNames: string[];
+}): AnyConfigurationModel[];
+/**
+ * Every track config a view can be offered, each assembly's sequence track
+ * first and then {@link filterTracks} over the list handed in.
+ */
+export declare function offeredTracks(tracks: AnyConfigurationModel[], self: {
+    view?: IStateTreeNode & {
+        type: string;
+    };
+    assemblyNames: string[];
+}): AnyConfigurationModel[];
+/**
+ * Which display a track opens with in a given view, and the declared entry
+ * that configures it: `{ type, conf }`, or undefined when the view draws none
+ * of the candidates or the requested type is not among them.
+ *
+ * The **type** is the requested one, checked rather than taken on faith (an
+ * unchecked one resolved its dangling `<trackId>-<type>` id back to the
+ * track's default display, and the caller was told it got what it asked for),
+ * else the first candidate among the view's own display types, else the first
+ * it draws at all. The **config** is then the declared entry of that type,
+ * never another one the view supports: `display.type ===
+ * display.configuration.type` is the invariant `DisplayConfigurationReference`
+ * assumes when it falls back to resolving by type.
+ */
+export declare function pickDisplayForView({ candidates, declaredDisplays, requestedType, viewDisplayTypes, preferredDisplayTypes, }: {
+    /** {@link displayCandidates}, canonical names in preference order */
+    candidates: string[];
+    /** the config's display entries, their types canonical */
     declaredDisplays: DisplayConfSnapshot[];
     requestedType: string | undefined;
-    trackDisplayTypes: string[];
     viewDisplayTypes: string[];
+    /**
+     * The display types the view registered as its own, ahead of those it
+     * inherits through `extendedName`: a variant track on the circular view
+     * draws its chords, not the linear display the view also accepts as a
+     * ring, even where its config declares only the linear one.
+     */
+    preferredDisplayTypes?: Set<string>;
 }): {
     type: string;
     conf: DisplayConfSnapshot | undefined;
@@ -403,6 +425,14 @@ export declare function stripTrackIds(tracks: TrackSnapshot[]): {
 }[];
 export declare function hideTrackGeneric(self: GenericView, trackId: string): boolean;
 export declare function toggleTrackGeneric(self: GenericView, trackId: string): boolean;
+/**
+ * Start loading the state model and component of the display a track would
+ * open with, without opening it, for a caller that knows the track is coming.
+ * Anything that fails here is the launch's to report.
+ */
+export declare function warmTrackDisplayGeneric(self: GenericView, trackId: string, displayInitialSnapshot?: DisplayInitialSnapshot, assemblyName?: string): void;
+export declare function launchTrackGeneric(self: GenericView, trackId: string, initialSnapshot?: object, displayInitialSnapshot?: DisplayInitialSnapshot, inlineConf?: Record<string, unknown>): Promise<any>;
+export declare function launchToggleTrackGeneric(self: GenericView, trackId: string): Promise<boolean>;
 /**
  * Every track config the session can show, connection-supplied ones included.
  *
@@ -420,7 +450,31 @@ export declare function allSessionTracks(session: {
     connectionInstances?: {
         tracks: AnyConfigurationModel[];
     }[];
-}): (import("@jbrowse/mobx-state-tree").ModelInstanceTypeProps<Record<string, any>> & {
-    setSubschema(slotName: string, data: Record<string, unknown>): any;
-    setSlot(slotName: string, value: unknown): void;
-} & IStateTreeNode<import("../configuration/types.ts").AnyConfigurationSchemaType>)[];
+}): AnyConfigurationModel[];
+/**
+ * The session's annotation for `assemblyName`, as trackIds: what a view opened
+ * on another genome starts with. Only FeatureTracks, not everything configured
+ * for the assembly — an alignments track turned on behind the user's back
+ * fetches data nobody asked for, and a FeatureTrack over a few kb is one tabix
+ * range query.
+ */
+export declare function annotationTrackIds(session: {
+    tracks: AnyConfigurationModel[];
+    connectionInstances?: {
+        tracks: AnyConfigurationModel[];
+    }[];
+    assemblyManager: AssemblyNameResolver;
+}, assemblyName: string): string[];
+/**
+ * One assembly on its own in a linear genome view, at `loc`. Keyed on `id`:
+ * following several alignments to one genome re-navigates the view rather than
+ * stacking a new one each time.
+ */
+export declare function openAssemblyInLinearView({ session, id, assemblyName, loc, tracks, }: {
+    session: AbstractViewContainer;
+    id: string;
+    assemblyName: string;
+    loc: string;
+    tracks: TrackInit[];
+}): Promise<void>;
+export declare function openMateLabel(assemblyName: string): string;