@jbrowse/product-core 4.3.0 → 5.0.0-beta.1

package/esm/Session/BaseSession.d.ts

@@ -1,35 +1,334 @@
 import type { BaseRootModelType } from '../RootModel/BaseRootModel.ts';
+import type { HeldNode } from '../pruneUnbuildableNodes.ts';
 import type PluginManager from '@jbrowse/core/PluginManager';
-import type { BaseAssemblyConfigSchema } from '@jbrowse/core/assemblyManager';
+import type { BaseAssemblyConfigModel } from '@jbrowse/core/assemblyManager';
 import type { AnyConfigurationSchemaType } from '@jbrowse/core/configuration';
+import type { AnimationMode, DialogComponentType, TrackConfigChange } from '@jbrowse/core/util';
 import type { IAnyStateTreeNode, Instance } from '@jbrowse/mobx-state-tree';
-export declare function BaseSessionModel<ROOT_MODEL_TYPE extends BaseRootModelType, JB_CONFIG_SCHEMA extends AnyConfigurationSchemaType>(_pluginManager: PluginManager): import("@jbrowse/mobx-state-tree").IModelType<{
+type DoneCallback = (doneCallback: () => void) => [DialogComponentType, Record<string, unknown>];
+/**
+ * #stateModel BaseSessionModel
+ *
+ * base session shared by all JBrowse products. Be careful what you include
+ * here, everything will use it.
+ */
+export declare function BaseSessionModel<ROOT_MODEL_TYPE extends BaseRootModelType, JB_CONFIG_SCHEMA extends AnyConfigurationSchemaType>(_pluginManager: PluginManager): import("@jbrowse/mobx-state-tree").IModelType<Omit<{
+    /**
+     * #property
+     */
     id: import("@jbrowse/mobx-state-tree").IOptionalIType<import("@jbrowse/mobx-state-tree").ISimpleType<string>, [undefined]>;
+    /**
+     * #property
+     */
     name: import("@jbrowse/mobx-state-tree").ISimpleType<string>;
-    margin: import("@jbrowse/mobx-state-tree").IType<number | undefined, number, number>;
-}, {
+    /**
+     * #property
+     * used to keep track of which view is in focus
+     */
+    focusedViewId: import("@jbrowse/mobx-state-tree").IMaybe<import("@jbrowse/mobx-state-tree").ISimpleType<string>>;
+    /**
+     * #property
+     * one session-wide toggle for all region highlight bands (URL/view
+     * highlights and bookmark overlays)
+     */
+    highlightsVisible: import("@jbrowse/mobx-state-tree").IOptionalIType<import("@jbrowse/mobx-state-tree").ISimpleType<boolean>, [undefined]>;
+    /**
+     * #property
+     * views, tracks, displays and widgets `pruneUnbuildableNodes` took out of
+     * the tree because this build has no plugin for their type, each with the
+     * anchor that puts it back. Opaque here on purpose — nothing in the
+     * session reads it, and the shape belongs to that module.
+     *
+     * It is a **declared property** rather than data riding along in the
+     * snapshot because MST silently drops an undeclared key: without this
+     * line the held nodes survive the prune and then vanish the moment
+     * `setSession` builds the tree, and every unit test of the prune still
+     * passes. `heldNodesSurviveTheSession.test.ts` is the canary.
+     */
+    heldForMissingPlugins: import("@jbrowse/mobx-state-tree").IOptionalIType<import("@jbrowse/mobx-state-tree").IType<HeldNode[] | undefined, HeldNode[] | undefined, HeldNode[] | undefined>, [undefined]>;
+}, never>, {
+    /**
+     * #volatile
+     * this is the globally "selected" object. can be anything. code that
+     * wants to deal with this should examine it to see what kind of thing it
+     * is.
+     */
     selection: unknown;
+    /**
+     * #volatile
+     * this is the globally "hovered" object. can be anything. code that
+     * wants to deal with this should examine it to see what kind of thing it
+     * is.
+     */
     hovered: unknown;
+    /**
+     * #volatile
+     */
+    queueOfDialogs: [DialogComponentType, Record<string, unknown>][];
+    /**
+     * #volatile
+     * runtime user-preference overrides keyed by preference id, resolved by
+     * `getPreference` against the `configuration.preferences` admin defaults.
+     * Empty here (config-only); products that let users edit preferences load
+     * and persist these via localStorage. A runtime override map layered over
+     * config defaults, kept off the snapshot since prefs are local UI.
+     *
+     * An `observable.map` (not a plain object reassigned wholesale) so each
+     * preference is its own tracked key: writing one (`setScrollZoom`) can't
+     * invalidate a reader of another (`getDisplayTypeDefault` in a track's
+     * `rpcProps`). A single spread-replaced object made every setter wake
+     * every reader, so toggling scroll-to-zoom re-fetched every track. For the
+     * same reason each promoted per-display-type default is a flat composite
+     * key (see `displayTypeDefaultKey`), not a single nested `displayTypeDefaults`
+     * object — promoting one default can't wake readers of a different one.
+     *
+     * `deep: false` is load-bearing, not a micro-optimization. The default
+     * enhancer wraps an object/array value in a MobX Proxy on `set`, and a
+     * promoted default is handed straight back out by `getConf` — so an
+     * object-valued promotable slot (alignments `colorBy`) put a Proxy into
+     * `rpcProps()`, and V8's structured-clone serializer rejects a Proxy:
+     * `worker.postMessage` threw `DataCloneError` on the next fetch of any
+     * track following that default (electron IPC and `structuredClone` in the
+     * share bake likewise). The map still notifies per key on `set`, so shallow
+     * values lose no reactivity — and nothing can mutate a preference in place,
+     * because `setPreferenceOverride` freezes what it stores.
+     */
+    preferencesOverrides: import("mobx").ObservableMap<string, unknown>;
 } & {
+    /**
+     * #getter
+     */
     readonly root: import("@jbrowse/mobx-state-tree").TypeOrStateTreeNodeToStateTreeNode<ROOT_MODEL_TYPE>;
 } & {
+    /**
+     * #getter
+     */
     readonly jbrowse: any;
+    /**
+     * #getter
+     */
     readonly rpcManager: import("@jbrowse/core/rpc/RpcManager").default;
+    /**
+     * #getter
+     */
     readonly configuration: Instance<JB_CONFIG_SCHEMA>;
+    /**
+     * #getter
+     */
     readonly adminMode: boolean;
-    readonly textSearchManager: import("@jbrowse/core/util").TextSearchManager;
+    /**
+     * #getter
+     */
+    readonly textSearchManager: import("@jbrowse/core/TextSearch/TextSearchManager").default;
 } & {
-    readonly assemblies: Instance<BaseAssemblyConfigSchema>[];
+    /**
+     * #getter
+     */
+    readonly assemblies: BaseAssemblyConfigModel[];
+    /**
+     * #getter
+     */
+    readonly DialogComponent: DialogComponentType | undefined;
+    /**
+     * #getter
+     */
+    readonly DialogProps: Record<string, unknown> | undefined;
 } & {
+    /**
+     * #method
+     * the admin/embedder `configuration.preferences` value for a key, ignoring
+     * any runtime override — i.e. what a reset falls back to. Exposed rather
+     * than inlined because "differs from the default" is a question the
+     * Preferences reset diff asks about settings this map doesn't hold (see
+     * `defaultUseWorkspaces`).
+     */
+    getPreferenceDefault(key: string): unknown;
+    /**
+     * #method
+     * resolved value of a user preference: a runtime override if the user set
+     * one, otherwise the admin/embedder `configuration.preferences` default.
+     * The override map is empty unless the product loads it (web/desktop).
+     */
+    getPreference(key: string): unknown;
+    /**
+     * #method
+     * resolved value of a per-display-type slot default the user promoted
+     * (see `setDisplayTypeDefault`); undefined when nothing was promoted.
+     */
+    getDisplayTypeDefault(displayType: string, slot: string): unknown;
+    /**
+     * #method
+     * every per-display-type default the user has promoted, as
+     * `{ displayType, slot, value }` — the inventory the Preferences dialog
+     * lists and clears one at a time (`setDisplayTypeDefault(…, undefined)`).
+     *
+     * Here rather than filtered out of `getPreferenceChanges` by the dialog,
+     * because the composite-key layout is this file's: a consumer that
+     * recognized these rows by matching the path head is exactly the coupling
+     * `DISPLAY_TYPE_DEFAULTS_PATH_HEAD` stopped being exported over, where a
+     * rename on one side alone silently no-ops the other.
+     */
+    getDisplayTypeDefaults(): {
+        displayType: string;
+        slot: string;
+        value: unknown;
+    }[];
+    /**
+     * #method
+     * every runtime preference-override that currently differs from its
+     * config/admin default, as `{ path, from, to }` rows — the exact set
+     * `clearPreferenceOverrides` reverts. Backs the confirmation diff shown
+     * before "Reset to defaults" (mirrors the per-track changes dialog). A
+     * scalar pref (animationMode, scrollZoom) whose override equals the
+     * default is omitted (reverting it is a no-op); each promoted
+     * per-display-type default is always a difference from the un-promoted
+     * state, so `from` reads "(default)".
+     */
+    getPreferenceChanges(): TrackConfigChange[];
+} & {
+    /**
+     * #getter
+     * resolved feature-layout animation mode (never undefined)
+     */
+    readonly animationMode: AnimationMode;
+    /**
+     * #getter
+     * resolved scroll-to-zoom preference. Global and personal (never shared in
+     * a session snapshot); every wheel-zoom view reads this single value.
+     */
+    readonly scrollZoom: boolean;
+    /**
+     * #getter
+     * resolved thousand-separator preference. Read for display in the
+     * Preferences dialog; the formatter itself reads a plain module variable
+     * set at startup in each realm (see `setNumberGrouping`), because worker-
+     * built strings can't see a main-thread observable.
+     */
+    readonly numberGrouping: boolean;
+} & {
+    afterAttach(): void;
+    /**
+     * #action
+     * set the global selection, i.e. the globally-selected object. can be a
+     * feature, a view, just about anything
+     *
+     * A feature is unwrapped on the way in, so app state never holds a
+     * jexlFeatureProxy. `isFeature` accepts a proxy, but on one `id` is a
+     * data field rather than the method the Feature type promises — every
+     * consumer doing `isFeature(selection) ? selection.id() : …` would throw.
+     */
     setSelection(thing: unknown): void;
+    /**
+     * #action
+     * clears the global selection
+     */
     clearSelection(): void;
+    /**
+     * #action
+     */
     setHovered(thing: unknown): void;
-}, 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]>;
-    name: import("@jbrowse/mobx-state-tree").ISimpleType<string>;
-    margin: import("@jbrowse/mobx-state-tree").IType<number | undefined, number, number>;
-}>>;
+    /**
+     * #action
+     * toggle all region highlight bands across every view
+     */
+    setHighlightsVisible(arg: boolean): void;
+    /**
+     * #action
+     * turn highlight bands back on, so a newly made highlight or bookmark is
+     * never silently swallowed by an earlier "highlights off"
+     */
+    revealHighlights(): void;
+    /**
+     * #action
+     * set a runtime user-preference override (see `getPreference`). Mutates
+     * volatile state; products persist these to localStorage. An `undefined`
+     * value deletes the key (rather than leaving a phantom entry that
+     * `getPreference` reads as absent) so the store never holds dead keys.
+     */
+    setPreferenceOverride(key: string, value: unknown): void;
+    /**
+     * #action
+     * clear every runtime preference override at once — scrollZoom,
+     * animationMode, and every promoted per-display-type default (see
+     * `setDisplayTypeDefault`) — so each falls back to its config/admin
+     * default. Backs the Preferences dialog "Reset to defaults" button.
+     */
+    clearPreferenceOverrides(): void;
+    /**
+     * #action
+     * clear a single runtime preference override (see `getPreference`) so it
+     * falls back to its config/admin default. Backs the per-entry reset in the
+     * Preferences dialog "Reset to defaults" confirmation.
+     */
+    clearPreferenceOverride(key: string): void;
+    /**
+     * #action
+     * revert one row emitted by `getPreferenceChanges`, addressed by its
+     * display `path`. Backs the per-entry reset in the Preferences dialog's
+     * "Reset to defaults" confirmation.
+     *
+     * Lives here rather than in that dialog because this model owns both path
+     * shapes it has to undo: a promoted per-display-type default, whose row
+     * path is a readable label over a flat composite storage key, and every
+     * other override, whose path *is* its key. The dialog used to re-derive
+     * the first case from an exported path-head constant.
+     */
+    resetPreferenceChange(path: string[]): void;
+    /**
+     * #action
+     * set the global scroll-to-zoom preference (see the `scrollZoom` getter)
+     */
+    setScrollZoom(flag: boolean): void;
+    /**
+     * #action
+     * promote (or, with `value` undefined, clear) a per-display-type slot
+     * default. Just a preference override under one flat composite key (see
+     * `displayTypeDefaultKey`), so it persists and independently tracks like
+     * any other pref, and clearing deletes only that key.
+     */
+    setDisplayTypeDefault(displayType: string, slot: string, value: unknown): void;
+    /**
+     * #action
+     */
+    setName(str: string): void;
+    /**
+     * #action
+     * `undefined` is "no view is focused", which the property has always been
+     * able to hold (`types.maybe`) and this had no way to spell. Nothing
+     * cleared it on teardown as a result: a view that was focused when it left
+     * the session left its id behind, and since every consumer compares
+     * `focusedViewId === view.id`, the id matched nothing, the focus ring
+     * vanished with nothing to say why, and the dead id persisted into a saved
+     * or shared session. `takeOut` clears it now.
+     */
+    setFocusedViewId(viewId: string | undefined): void;
+    /**
+     * #action
+     */
+    removeActiveDialog(): void;
+    /**
+     * #action
+     */
+    queueDialog(doneCallback: DoneCallback): void;
+} & {
+    snackbarMessages: import("mobx").IObservableArray<import("@jbrowse/core/ui/SnackbarModel").SnackbarMessage>;
+    errorDialog: import("@jbrowse/core/ui/SnackbarModel").ErrorDialogState | undefined;
+} & {
+    readonly snackbarMessageSet: Map<string, import("@jbrowse/core/ui/SnackbarModel").SnackbarMessage>;
+} & {
+    notify(message: string, level?: import("@jbrowse/core/util").NotificationLevel, action?: import("@jbrowse/core/util").SnackAction | import("@jbrowse/core/util").SnackAction[]): void;
+    notifyError(errorMessage: string, error?: unknown, extra?: unknown, action?: import("@jbrowse/core/util").SnackAction): void;
+    setErrorDialog(state: import("@jbrowse/core/ui/SnackbarModel").ErrorDialogState | undefined): void;
+    pushSnackbarMessage(message: string, level?: import("@jbrowse/core/util").NotificationLevel, actions?: import("@jbrowse/core/util").SnackAction[]): void;
+    popSnackbarMessage(): import("@jbrowse/core/ui/SnackbarModel").SnackbarMessage | undefined;
+    removeSnackbarMessage(message: string): void;
+}, import("@jbrowse/mobx-state-tree")._NotCustomized, import("@jbrowse/mobx-state-tree")._NotCustomized>;
+/** Session mixin MST type for the most basic session */
 export type BaseSessionType = ReturnType<typeof BaseSessionModel>;
+/** Instance of the most basic possible session */
 export type BaseSession = Instance<BaseSessionType>;
+/** Type guard for BaseSession */
 export declare function isBaseSession(thing: IAnyStateTreeNode): thing is BaseSession;
+/** Type guard for whether a thing is JBrowse session */
 export declare function isSession(thing: unknown): thing is BaseSession;
+export {};