@jbrowse/core 4.2.1 → 5.0.0-beta.1

package/esm/pluggableElementTypes/models/BaseDisplayModel.js

@@ -1,106 +1,214 @@
-import { getParent, types } from '@jbrowse/mobx-state-tree';
-import { getConf } from "../../configuration/index.js";
-import { getContainingTrack, getContainingView, getEnv, } from "../../util/index.js";
-import { getParentRenderProps } from "../../util/tracks.js";
-import { ElementId } from "../../util/types/mst.js";
+import { hasParent, isAlive, types } from '@jbrowse/mobx-state-tree';
+import { getConf } from '../../configuration/index.js';
+import { getContainingTrack, getEnv, statusFraction, statusMessageText, } from '../../util/index.js';
+import { ElementId } from '../../util/types/mst.js';
+/**
+ * #stateModel BaseDisplay
+ * #category display
+ */
 function stateModelFactory() {
     return types
         .model('BaseDisplay', {
+        /**
+         * #property
+         */
         id: ElementId,
+        /**
+         * #property
+         */
         type: types.string,
-        rpcDriverName: types.maybe(types.string),
     })
         .volatile(() => ({
-        rendererTypeName: '',
+        // eslint-disable-next-line @typescript-eslint/no-unnecessary-type-assertion
         error: undefined,
         statusMessage: undefined,
+        /**
+         * #volatile
+         * determinate progress fraction [0,1] for the current status, or
+         * undefined when the in-flight phase is indeterminate. Set alongside
+         * `statusMessage` by `setStatusMessage`; a display that never shows a
+         * bar simply leaves it undefined.
+         */
+        statusProgress: undefined,
     }))
         .views(self => ({
+        /**
+         * #getter
+         */
+        get parentTrack() {
+            if (!hasParent(self)) {
+                console.warn(`[BaseDisplayModel] parentTrack accessed with no parent: alive=${isAlive(self)} type=${self.type}`);
+            }
+            return getContainingTrack(self);
+        },
+    }))
+        .views(self => ({
+        /**
+         * #getter
+         */
         get RenderingComponent() {
             const { pluginManager } = getEnv(self);
             return pluginManager.getDisplayType(self.type)
                 .ReactComponent;
         },
+        /**
+         * #getter
+         */
         get DisplayBlurb() {
             return null;
         },
+        /**
+         * #getter
+         */
         get adapterConfig() {
-            return getConf(this.parentTrack, 'adapter');
-        },
-        get parentTrack() {
-            return getContainingTrack(self);
-        },
+            // `Record<string, unknown>` is as narrow as this can honestly get: which
+            // adapter a track uses is open-ended, so the *contents* are
+            // unpredictable. The *shape* is not, and that is the part worth
+            // declaring. Leaving it to infer `getConf`'s `any` was the status quo and
+            // it propagated: every consumer's RPC arg and adapter spec takes
+            // `Record<string, unknown>`, so they accepted whatever they were handed,
+            // and two displays re-declared this getter locally just to annotate it.
+            //
+            // Not `| undefined` — see `BaseTrackModel.adapterConfig` for the probe
+            // showing the slot always materializes an object.
+            //
+            // This is a snapshot, so read a specific slot with an array path off the
+            // live node (`getConf(track, ['adapter', 'x'])`) rather than off this —
+            // `types.stripDefault` omits a slot at its default. See
+            // ../../configuration/CLAUDE.md.
+            return getConf(self.parentTrack, 'adapter');
+        },
+        /**
+         * #getter
+         * Returns true if the parent track is minimized. Used to skip
+         * expensive operations like autoruns when track is not visible.
+         */
         get isMinimized() {
-            return this.parentTrack.minimized;
-        },
-        get parentDisplay() {
-            try {
-                const parent = getParent(self);
-                const parentType = parent?.type;
-                if (typeof parentType === 'string' &&
-                    parentType.endsWith('Display')) {
-                    return parent;
-                }
-            }
-            catch {
-            }
+            return self.parentTrack.minimized;
+        },
+        /**
+         * #getter
+         * Overridable hook (default `undefined`): what the pointer is currently
+         * over, for readers **outside** the display. `LinearGenomeViewContainer`
+         * publishes it to `session.hovered`, the view-wide "what is the user
+         * pointing at" channel a plugin can subscribe to.
+         *
+         * Declared here because a cross-display consumer can only read a name the
+         * base declares — the same reason `SyntenyFetchStateMixin.fetchInert` is a
+         * hook rather than a getter each display invents. The container used to
+         * read `featureUnderMouse`, which only the wiggle, alignments and
+         * Manhattan families spelled that way — canvas said `hoveredFeature`,
+         * variants `hoveredGenotype` — so the channel carried a hover from a third
+         * of the display types and nothing said which. It also asked only
+         * `displays[0]` of each track.
+         *
+         * `unknown` because the payload genuinely differs — a read, a wiggle bin,
+         * a SNP, a genotype cell — and `session.hovered` is typed to match ("can
+         * be anything; code that wants to deal with this should examine it").
+         * Narrow it in the override.
+         */
+        get hoveredFeature() {
             return undefined;
         },
-        get effectiveRpcDriverName() {
-            if (self.rpcDriverName) {
-                return self.rpcDriverName;
-            }
-            if (this.parentDisplay?.effectiveRpcDriverName) {
-                return this.parentDisplay.effectiveRpcDriverName;
-            }
-            try {
-                return getConf(this.parentTrack, 'rpcDriverName') || undefined;
-            }
-            catch {
-                return undefined;
-            }
-        },
-    }))
-        .views(self => ({
-        renderProps() {
+        /**
+         * #getter
+         * Overridable hook (default `'feature'`): the SINGULAR word for one of
+         * the things this display draws, as a menu row or a chip says it —
+         * "Hide this read", "Showing 3 variants".
+         *
+         * Declared here for the same reason as `hoveredFeature` above: it is read
+         * across the display boundary, by chrome that has no idea which display
+         * it is drawing for (`SoloSelectionChip`, alignments' group-label
+         * overlay), and a name only the base declares is a name every such
+         * consumer can rely on. Two displays declared it independently and one of
+         * those declarations WAS this default.
+         *
+         * **A control keeps the generic word; content takes this one.** "Variant
+         * height" reads as a different setting from "Feature height" when it is
+         * the same one, so the shared menus stay on "feature" however the display
+         * answers here, and the noun varies where it names what the user is
+         * looking at — "Showing 3 variants", "Hide this read". A display drawing
+         * something the generic word already fits is right to leave this alone.
+         *
+         * Distinct from the per-hit noun a context menu takes off the clicked
+         * item's own `type` ("mRNA", "gene"); that names one annotation, this
+         * names what the track holds. The hit noun falls back to this.
+         */
+        get featureNoun() {
+            return 'feature';
+        },
+        /**
+         * #getter
+         * Overridable hook: which widget `openFeatureWidget` opens for one of
+         * this display's features. The default is the generic one, which is what
+         * a display drawing plain features wants and what the canvas base spelled
+         * out by hand.
+         *
+         * An override is a display whose features have a vocabulary of their own —
+         * a read, a variant, a synteny block — and the `id` is deliberately part
+         * of it: two displays naming one id share the drawer panel, which is the
+         * behaviour when the two are showing the same kind of thing.
+         */
+        get featureWidgetType() {
             return {
-                ...getParentRenderProps(self),
-                notReady: self.isMinimized || getContainingView(self).minimized,
-                rpcDriverName: self.effectiveRpcDriverName,
+                type: 'BaseFeatureWidget',
+                id: 'baseFeature',
             };
         },
+    }))
+        .views(self => ({
+        /**
+         * #method
+         * props passed to the renderer's React "Rendering" component.
+         * these are client-side only and never sent to the worker.
+         * includes displayModel and callbacks
+         */
         renderingProps() {
             return {
                 displayModel: self,
             };
         },
-        get rendererType() {
-            const { pluginManager } = getEnv(self);
-            return pluginManager.getRendererType(self.rendererTypeName);
-        },
-        get DisplayMessageComponent() {
-            return undefined;
-        },
+        /**
+         * #method
+         */
         trackMenuItems() {
             return [];
         },
-        get viewMenuActions() {
-            return [];
-        },
-        regionCannotBeRendered() {
-            return null;
-        },
     }))
         .actions(self => ({
-        setStatusMessage(arg) {
-            self.statusMessage = arg;
-        },
+        /**
+         * #action
+         */
+        setStatusMessage(status) {
+            // derive the indeterminate label and the determinate fraction from the
+            // one status transport; displays with no bar just ignore statusProgress
+            self.statusMessage = statusMessageText(status);
+            self.statusProgress = statusFraction(status);
+        },
+        /**
+         * #action
+         */
         setError(error) {
             self.error = error;
         },
-        setRpcDriverName(rpcDriverName) {
-            self.rpcDriverName = rpcDriverName;
-        },
+        /**
+         * #action
+         * Overridable hook (default no-op): drop whatever `hoveredFeature`
+         * reports. The writing twin of that getter, and what
+         * `installClearHoverOnViewportChange` calls.
+         *
+         * A display that STORES its hover owes an override; one that derives it
+         * from the live pointer (MAF, Hi-C, LD) owes nothing, and the default
+         * costs it nothing. Declared here so the clear can be installed for every
+         * display rather than remembered per display — forgetting it is the
+         * failure ARCHITECTURE.md's stored-hover section is about, and it used to
+         * be six closures at six call sites, which is six chances to omit one.
+         */
+        clearHoveredFeature() { },
+        /**
+         * #action
+         * base display reload does nothing, see specialized displays for details
+         */
         reload() { },
     }));
 }

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

@@ -1,74 +1,215 @@
-import { stringifyBED } from './saveTrackFileTypes/bed.ts';
-import { stringifyGBK } from './saveTrackFileTypes/genbank.ts';
-import { stringifyGFF3 } from './saveTrackFileTypes/gff3.ts';
 import type PluginManager from '../../PluginManager.ts';
+import type { RefNameMismatch } from '../../assemblyManager/refNameMismatch.ts';
 import type { AnyConfigurationSchemaType } from '../../configuration/index.ts';
 import type { MenuItem } from '../../ui/index.ts';
-import type { IAnyStateTreeNode, Instance } from '@jbrowse/mobx-state-tree';
-export declare function getCompatibleDisplays(self: IAnyStateTreeNode): ({
-    [x: string]: any;
-} & import("@jbrowse/mobx-state-tree/dist/internal").NonEmptyObject & {
-    setSubschema(slotName: string, data: Record<string, unknown>): Record<string, unknown> | ({
-        [x: string]: any;
-    } & import("@jbrowse/mobx-state-tree/dist/internal").NonEmptyObject & any & import("@jbrowse/mobx-state-tree").IStateTreeNode<AnyConfigurationSchemaType>);
-} & import("@jbrowse/mobx-state-tree").IStateTreeNode<AnyConfigurationSchemaType>)[];
+import type { DisplayModel } from './BaseDisplayModel.tsx';
+import type { FileTypeExporter } from './saveTrackFileTypes/types.ts';
+import type { IType, Instance } from '@jbrowse/mobx-state-tree';
+/**
+ * #stateModel BaseTrackModel
+ * #category track
+ *
+ * these MST models only exist for tracks that are *shown*. they should contain
+ * only UI state for the track, and have a reference to a track configuration.
+ * note that multiple displayed tracks could use the same configuration.
+ */
 export declare function createBaseTrackModel(pm: PluginManager, trackType: string, baseTrackConfig: AnyConfigurationSchemaType): import("@jbrowse/mobx-state-tree").IModelType<{
+    /**
+     * #property
+     */
     id: import("@jbrowse/mobx-state-tree").IOptionalIType<import("@jbrowse/mobx-state-tree").ISimpleType<string>, [undefined]>;
-    type: import("@jbrowse/mobx-state-tree").ISimpleType<string>;
-    configuration: AnyConfigurationSchemaType;
-    minimized: import("@jbrowse/mobx-state-tree").IType<boolean | undefined, boolean, boolean>;
-    pinned: import("@jbrowse/mobx-state-tree").IType<boolean | undefined, boolean, boolean>;
-    displays: import("@jbrowse/mobx-state-tree").IArrayType<import("@jbrowse/mobx-state-tree").IAnyType>;
+    /**
+     * #property
+     */
+    type: import("@jbrowse/mobx-state-tree").ILiteralType<string>;
+    /**
+     * #property
+     */
+    configuration: import("../../configuration/configurationSchema.ts").IConfigurationReference<AnyConfigurationSchemaType>;
+    /**
+     * #property
+     */
+    minimized: import("@jbrowse/mobx-state-tree").IOptionalIType<import("@jbrowse/mobx-state-tree").ISimpleType<boolean>, [undefined]>;
+    /**
+     * #property
+     */
+    pinned: import("@jbrowse/mobx-state-tree").IOptionalIType<import("@jbrowse/mobx-state-tree").ISimpleType<boolean>, [undefined]>;
+    /**
+     * #property
+     * The runtime plugin union (`pluggableMstType`) is typed only as
+     * `IAnyType`, erasing the element to `any`. Assert the concrete
+     * `DisplayModel` instance every registered display satisfies so reads
+     * (`activeDisplay`, `trackMenuItems`) are checked;
+     * create/snapshot stay `unknown` since the union's snapshot shape is
+     * genuinely dynamic (`replaceDisplay` writes a partial snapshot).
+     */
+    displays: import("@jbrowse/mobx-state-tree").IArrayType<IType<unknown, unknown, DisplayModel>>;
 }, {
+    /**
+     * Whether a height-resize gesture is in progress on this track. Set by
+     * whichever handle owns the drag — the view's track resize handle, or a
+     * handle a display draws inside itself — and read by displays that sit an
+     * expensive per-frame layer out of the gesture.
+     *
+     * On the track rather than the display because the gesture belongs to the
+     * container running it, not to whatever display happens to be active: the
+     * view can bracket a drag without knowing which display it landed on, and
+     * two handles on one track share one flag rather than racing to clear
+     * each other's.
+     */
+    resizing: boolean;
+} & {
+    /**
+     * #getter
+     */
     readonly trackId: string;
+    /**
+     * #getter
+     * determines which webworker to send the track to, currently based on trackId
+     */
     readonly rpcSessionId: string;
-    readonly name: any;
+    /**
+     * #getter
+     */
+    readonly name: string;
+    /**
+     * #getter
+     * this track's own name-search index, from the `textSearching`
+     * sub-config. `undefined` when the track has none.
+     *
+     * The path, not a bare `'textSearchAdapter'`: the slot is
+     * `textSearching.textSearchAdapter` (`baseTrackConfig.ts`), and a bare
+     * read of a name no schema declares returns `undefined` and reports
+     * nothing at any layer, so this getter answered `undefined` for every
+     * track ever configured with one. `TextSearchManager` reads the same slot
+     * by hand-walking `conf.textSearching.textSearchAdapter`, which is why
+     * nothing noticed.
+     */
     readonly textSearchAdapter: any;
-    readonly adapterConfig: any;
-    readonly viewMenuActions: MenuItem[];
-    readonly canConfigure: boolean | ({
-        [x: string]: any;
-    } & import("@jbrowse/mobx-state-tree/dist/internal").NonEmptyObject & {
-        setSubschema(slotName: string, data: Record<string, unknown>): Record<string, unknown> | ({
-            [x: string]: any;
-        } & import("@jbrowse/mobx-state-tree/dist/internal").NonEmptyObject & any & import("@jbrowse/mobx-state-tree").IStateTreeNode<AnyConfigurationSchemaType>);
-    } & import("@jbrowse/mobx-state-tree").IStateTreeNode<AnyConfigurationSchemaType>) | undefined;
+    /**
+     * #getter
+     */
+    readonly adapterConfig: Record<string, unknown>;
+    /**
+     * #getter
+     * a shown track always has at least one display
+     */
+    readonly activeDisplay: DisplayModel & import("@jbrowse/mobx-state-tree").IStateTreeNode<IType<unknown, unknown, DisplayModel>>;
+    /**
+     * #getter
+     */
+    readonly canConfigure: boolean;
 } & {
+    /**
+     * #getter
+     * Set when this track's file and one of its assemblies share no reference
+     * name at all — the `1/2/3` file loaded against a `chr1/chr2/chr3`
+     * assembly, which otherwise draws an empty track and says nothing.
+     *
+     * The verdict is reached in `loadRefNameMap`, which is the only place both
+     * name sets are in scope, and recorded on the *assembly* because nothing
+     * in the assembly manager can reach a track (the session is a sibling
+     * subtree, so `getSession` from there finds only the root). The lookup
+     * inverts that: the record is keyed by adapter cache key, which is exactly
+     * what `rpcSessionId` already is, so a track finds its own with no
+     * plumbing in between.
+     *
+     * The names come from `getConfAssemblyNamesOrNone`, not from a raw
+     * `assemblyNames` slot read: this model is shared by every track type, and
+     * `ReferenceSequenceTrack`'s schema does not declare that slot — it names
+     * its assembly by being the `sequence` of one. A raw read there returns
+     * `undefined` with no diagnostic at any layer, so the getter was inert for
+     * that one track type while looking like it worked. The `OrNone` half is
+     * what keeps this total: it runs on every render of every track label, and
+     * an unanswerable question must not become a thrown getter.
+     *
+     * Diagnostic only. It gates nothing, and a track carrying one still loads,
+     * still fetches and still draws whatever it can.
+     */
+    readonly refNameMismatch: RefNameMismatch | undefined;
+    /**
+     * #getter
+     */
     readonly adapterType: import("../AdapterType.ts").default;
 } & {
+    /**
+     * #action
+     */
     setPinned(flag: boolean): void;
+    /**
+     * #action
+     */
     setMinimized(flag: boolean): void;
-    showDisplay(displayId: string, initialSnapshot?: {}): void;
-    hideDisplay(displayId: string): number;
-    replaceDisplay(oldDisplayId: string, newDisplayId: string, initialSnapshot?: {}): void;
+    /**
+     * #action
+     */
+    setResizing(flag: boolean): void;
+    /**
+     * #action
+     */
+    replaceDisplay(oldDisplayId: string, newDisplayId: string, initialSnapshot?: any): void;
+    /**
+     * #action
+     * Persist any config-schema mutation (quick track-menu edits calling
+     * `setSlot` directly, or the full Settings dialog) back to the session,
+     * debounced, mirroring ConfigurationEditorWidget's own save. Both savers
+     * intentionally coexist — this one covers direct setSlot edits on a shown
+     * track, the widget covers an unshown track edited from the selector (no
+     * BaseTrackModel). When both fire they compute an identical delta, deduped
+     * in updateTrackConfiguration; don't drop one to "simplify". `reaction`
+     * (not `autorun`) on purpose: `self.configuration` is defined
+     * immediately on attach, unlike ConfigurationEditorWidget's `target`
+     * (which starts undefined), so an autorun's guaranteed first run would
+     * otherwise schedule a spurious flush for every track ever shown, even
+     * completely untouched ones — `reaction` only fires on an actual change.
+     *
+     * `equals: compareStructural` is load-bearing, not an optimization:
+     * `self.configuration` is a re-resolving reference, and persisting a save
+     * swaps the resolved node identity (admin `updateTrackConf` replaces the
+     * frozen `jbrowse.tracks` entry, rehydrating a brand-new MST node; the
+     * non-admin path reconciles in place but still churns once). Referential
+     * comparison would treat every such swap as a fresh change and re-fire the
+     * save, which for the admin/desktop path (new node every write) is an
+     * unbounded debounced loop. Structural comparison settles once the content
+     * stops changing.
+     */
+    afterAttach(): void;
 } & {
-    saveTrackFileFormatOptions(): {
-        gff3: {
-            name: string;
-            extension: string;
-            callback: typeof stringifyGFF3;
-        };
-        genbank: {
-            name: string;
-            extension: string;
-            callback: typeof stringifyGBK;
-            helpText: string;
-        };
-        bed: {
-            name: string;
-            extension: string;
-            callback: typeof stringifyBED;
-        };
-    };
+    /**
+     * #getter
+     * Whether this track's adapter writes an export format itself, rather
+     * than the save dialog rebuilding one out of rendered features. A claim
+     * about the adapter type, not about a given format — the fetch still
+     * falls back when the adapter declines the one that was asked for.
+     */
+    readonly exportsDataViaAdapter: boolean;
+    /**
+     * #getter
+     * What "Save track data" may pull before it asks. The adapter's own
+     * `fetchSizeLimit` where it declares one, so a save does not quietly
+     * disagree with the size this track's display already refuses to render;
+     * otherwise a default. Deliberately generous — unlike the display's gate
+     * this is a confirmation rather than a refusal, and the user asked for
+     * these bytes by name.
+     */
+    readonly exportByteLimit: number;
+    /**
+     * #method
+     */
+    saveTrackFileFormatOptions(): Record<string, FileTypeExporter>;
 } & {
+    /**
+     * #getter
+     * the "Save track data" menu entry. Kept separate from trackMenuItems so
+     * consumers (e.g. the LGV track-label menu) can place it alongside the
+     * session's Settings/Copy/Delete track actions without fishing it back out
+     * of the general list
+     */
+    readonly saveTrackDataMenuItem: MenuItem;
+    /**
+     * #method
+     */
     trackMenuItems(): MenuItem[];
-}, import("@jbrowse/mobx-state-tree")._NotCustomized, import("@jbrowse/mobx-state-tree").ModelSnapshotType<{
-    id: import("@jbrowse/mobx-state-tree").IOptionalIType<import("@jbrowse/mobx-state-tree").ISimpleType<string>, [undefined]>;
-    type: import("@jbrowse/mobx-state-tree").ISimpleType<string>;
-    configuration: AnyConfigurationSchemaType;
-    minimized: import("@jbrowse/mobx-state-tree").IType<boolean | undefined, boolean, boolean>;
-    pinned: import("@jbrowse/mobx-state-tree").IType<boolean | undefined, boolean, boolean>;
-    displays: import("@jbrowse/mobx-state-tree").IArrayType<import("@jbrowse/mobx-state-tree").IAnyType>;
-}>>;
+}, import("@jbrowse/mobx-state-tree")._NotCustomized, import("@jbrowse/mobx-state-tree")._NotCustomized>;
 export type BaseTrackStateModel = ReturnType<typeof createBaseTrackModel>;
 export type BaseTrackModel = Instance<BaseTrackStateModel>;