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

package/esm/Session/BaseSession.d.ts

@@ -1,35 +1,309 @@
 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 { HighlightType } from '@jbrowse/core/util/highlights';
 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
+     * translucent bands over genomic regions; every view draws the ones on
+     * its own assemblies
+     */
+    highlights: import("@jbrowse/mobx-state-tree").IOptionalIType<import("@jbrowse/mobx-state-tree").IArrayType<import("@jbrowse/mobx-state-tree").IType<HighlightType, HighlightType, HighlightType>>, [undefined]>;
+    /**
+     * #property
+     */
+    highlightsVisible: import("@jbrowse/mobx-state-tree").IOptionalIType<import("@jbrowse/mobx-state-tree").ISimpleType<boolean>, [undefined]>;
+    /**
+     * #property
+     * whether a band's label is written on it
+     */
+    highlightLabelsVisible: 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. Nothing in the session reads its contents,
+     * and `pruneUnbuildableNodes` defines their structure.
+     *
+     * It is a **declared property** because MST drops undeclared snapshot
+     * keys without error. Without this declaration the held nodes survive
+     * the prune and are then discarded when `setSession` builds the tree,
+     * while every unit test of the prune still passes.
+     * `heldNodesSurviveTheSession.test.ts` tests that they survive.
+     */
+    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. A single spread-replaced object made
+     * every setter wake every reader, so toggling scroll-to-zoom re-fetched
+     * every track.
+     *
+     * `deep: false` keeps an object-valued preference a plain object rather
+     * than a MobX Proxy, which V8's structured-clone serializer rejects. 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
+     * every scalar preference override that currently differs from its
+     * config/admin default, as `{ path, from, to }` rows whose path is the
+     * override's own key. A scalar pref (animationMode, scrollZoom) whose
+     * override equals the default is omitted, since reverting it is a no-op.
+     */
+    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
+     */
+    setHighlightsVisible(arg: boolean): void;
+    /**
+     * #action
+     */
+    setHighlightLabelsVisible(arg: boolean): void;
+    /**
+     * #action
+     * an identical entry is not added twice, so a spec launched again does not
+     * stack its bands. Adding shows the bands again, since a highlight made
+     * while they are off would otherwise read as nothing happening
+     */
+    addHighlight(highlight: HighlightType): void;
+    /**
+     * #action
+     */
+    removeHighlight(highlight: HighlightType): void;
+    /**
+     * #action
+     */
+    updateHighlight(old: HighlightType, updates: Partial<HighlightType>): void;
+    /**
+     * #action
+     */
+    setHighlights(highlights: HighlightType[]): 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, 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
+     * set the global scroll-to-zoom preference (see the `scrollZoom` getter)
+     */
+    setScrollZoom(flag: boolean): 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;
+    /**
+     * #action
+     */
+    removeDialog(entry: [DialogComponentType, Record<string, unknown>]): 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;
+} & {
+    afterAttach(): 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 {};