@jbrowse/core 4.3.0 → 5.0.0-beta.10

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

@@ -1,52 +1,272 @@
 import type { MenuItem } from '../../ui/index.ts';
+import type { AbstractTrackModel, AbstractViewModel } from '../../util/types/index.ts';
 import type { Instance } from '@jbrowse/mobx-state-tree';
+/**
+ * #stateModel BaseViewModel
+ * #category view
+ */
 declare const BaseViewModel: import("@jbrowse/mobx-state-tree").IModelType<{
+    /**
+     * #property
+     */
     id: import("@jbrowse/mobx-state-tree").IOptionalIType<import("@jbrowse/mobx-state-tree").ISimpleType<string>, [undefined]>;
+    /**
+     * #property
+     * displayName is displayed in the header of the view, or assembly names
+     * being used if none is specified
+     */
     displayName: import("@jbrowse/mobx-state-tree").IMaybe<import("@jbrowse/mobx-state-tree").ISimpleType<string>>;
-    minimized: import("@jbrowse/mobx-state-tree").IType<boolean | undefined, boolean, boolean>;
+    /**
+     * #property
+     * collapse the view to its header bar, keeping it in the session rather
+     * than closing it
+     */
+    minimized: import("@jbrowse/mobx-state-tree").IOptionalIType<import("@jbrowse/mobx-state-tree").ISimpleType<boolean>, [undefined]>;
 }, {
     width: number;
+    /**
+     * Whether the container has this view's body in the DOM.
+     *
+     * `ViewContainer` mounts a view's body only while an IntersectionObserver
+     * says it is on screen, to hold the app under the WebGL2 context ceiling
+     * (`reference/GPU_CONTEXT_BUDGET.md`). A view below the fold therefore has
+     * no canvas, so nothing ever calls `markCanvasDrawn` and the pre-first-paint
+     * term of `displayPhase` pins every display in it at `loading` with nothing
+     * left to resolve it — which parks `[data-app-phase="ready"]` for the whole
+     * app on a view the user cannot see.
+     *
+     * Defaults true so the containers that always mount a body — embedded
+     * views, workspace panels, and any test rendering a display directly — are
+     * unaffected and need not set it.
+     *
+     * The raw flag, written by this view's own container. A display asks
+     * `effectiveBodyMounted` instead, because a nested view has no container of
+     * its own.
+     */
+    bodyMounted: boolean;
 } & {
+    /**
+     * #getter
+     * Overridable hook (default true): whether this view's mounted body
+     * renders its own displays. A linear genome view collapsed to its ruler
+     * mounts the scalebar and none of its tracks, so a display in it can no
+     * more paint than one in a view scrolled off screen. Views nested in this
+     * one are unaffected: they paint wherever their own body is.
+     */
+    readonly rendersDisplays: boolean;
+    /**
+     * #getter
+     * Whether this view's displays have a canvas to paint into: its body is in
+     * the DOM, counting the views it is nested inside, and the body renders
+     * them (`rendersDisplays`). This is the question a display's phase asks.
+     *
+     * `bodyMounted` alone answers the DOM half only for a view a container
+     * renders directly. A view nested in another view (a synteny row, a
+     * breakpoint panel) has no container writing its flag, so it reads `true`
+     * forever while its whole subtree is out of the DOM, and every display in
+     * it waits for a first paint that nothing will make — the hang this flag
+     * exists to prevent, one level down.
+     *
+     * An ancestor that does not carry the flag at all leaves the answer alone
+     * rather than excusing the paint: only an explicit `false` unmounts, so a
+     * duck-typed stand-in that forgot it keeps waiting, which is the failure
+     * that shows up as a slow test rather than as a picture of an empty view.
+     */
+    readonly effectiveBodyMounted: boolean;
+    /**
+     * #method
+     */
     menuItems(): MenuItem[];
+    /**
+     * #getter
+     * The tracks this view puts in the census — its own, not a nested view's.
+     *
+     * Empty here, and overridden by the views that have any: the base cannot
+     * read `self.tracks` for them, because what a view keeps under that name
+     * is the view's business. react-msaview's holds its MSA annotation rows —
+     * `{ReactComponent, model}` objects with no configuration and no displays
+     * — and a base that helped itself to them handed them to the readiness
+     * marker as tracks, which error-paged every session holding an MSA view.
+     */
+    readonly ownTracks: AbstractTrackModel[];
+    /**
+     * #getter
+     * The views nested directly inside this one, which the census counts as
+     * views in their own right — a synteny stack's genome rows, a breakpoint
+     * split view's panels.
+     *
+     * Empty here for the same reason, and the dotplot is why it has to be a
+     * declaration rather than a walk of `views`: that prop name holds its two
+     * 1D *axis* models, which are view-shaped and are not views the user
+     * opened. No structural test separates the two — only the view knows.
+     */
+    readonly ownViews: AbstractViewModel[];
 } & {
+    /**
+     * #action
+     */
     setDisplayName(name: string): void;
+    /**
+     * #action
+     * width is an important attribute of the view model, when it becomes set,
+     * it often indicates when the app can start drawing to it. certain views
+     * like lgv are strict about this because if it tries to draw before it
+     * knows the width it should draw to, it may start fetching data for
+     * regions it doesn't need to
+     *
+     * setWidth is updated by a ResizeObserver generally, the views often need
+     * to know how wide they are to properly draw genomic regions
+     */
     setWidth(newWidth: number): void;
+    /**
+     * #action
+     * See `bodyMounted`. Written by the view's container, which is the only
+     * thing that knows whether it rendered the body.
+     */
+    setBodyMounted(flag: boolean): void;
+    /**
+     * #action
+     */
     setMinimized(flag: boolean): 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]>;
-    displayName: import("@jbrowse/mobx-state-tree").IMaybe<import("@jbrowse/mobx-state-tree").ISimpleType<string>>;
-    minimized: import("@jbrowse/mobx-state-tree").IType<boolean | undefined, boolean, boolean>;
-}>>;
+}, import("@jbrowse/mobx-state-tree")._NotCustomized, import("@jbrowse/mobx-state-tree")._NotCustomized>;
 export default BaseViewModel;
 export type IBaseViewModel = Instance<typeof BaseViewModel> & {
     type: string;
+    assemblyNames?: string[];
 };
-export declare const BaseViewModelWithDisplayedRegions: import("@jbrowse/mobx-state-tree").IModelType<{
+export declare const BaseViewModelWithDisplayedRegions: import("@jbrowse/mobx-state-tree").IModelType<Omit<{
+    /**
+     * #property
+     */
     id: import("@jbrowse/mobx-state-tree").IOptionalIType<import("@jbrowse/mobx-state-tree").ISimpleType<string>, [undefined]>;
+    /**
+     * #property
+     * displayName is displayed in the header of the view, or assembly names
+     * being used if none is specified
+     */
     displayName: import("@jbrowse/mobx-state-tree").IMaybe<import("@jbrowse/mobx-state-tree").ISimpleType<string>>;
-    minimized: import("@jbrowse/mobx-state-tree").IType<boolean | undefined, boolean, boolean>;
-} & {
-    displayedRegions: import("@jbrowse/mobx-state-tree").IArrayType<import("@jbrowse/mobx-state-tree").IModelType<{
+    /**
+     * #property
+     * collapse the view to its header bar, keeping it in the session rather
+     * than closing it
+     */
+    minimized: import("@jbrowse/mobx-state-tree").IOptionalIType<import("@jbrowse/mobx-state-tree").ISimpleType<boolean>, [undefined]>;
+}, "displayedRegions"> & {
+    displayedRegions: import("@jbrowse/mobx-state-tree").IArrayType<import("@jbrowse/mobx-state-tree").IModelType<Omit<{
         refName: import("@jbrowse/mobx-state-tree").ISimpleType<string>;
         start: import("@jbrowse/mobx-state-tree").ISimpleType<number>;
         end: import("@jbrowse/mobx-state-tree").ISimpleType<number>;
         reversed: import("@jbrowse/mobx-state-tree").IOptionalIType<import("@jbrowse/mobx-state-tree").ISimpleType<boolean>, [undefined]>;
-    } & {
+    }, "assemblyName"> & {
         assemblyName: import("@jbrowse/mobx-state-tree").ISimpleType<string>;
     }, {
         setRefName(newRefName: string): void;
     }, import("@jbrowse/mobx-state-tree")._NotCustomized, import("@jbrowse/mobx-state-tree")._NotCustomized>>;
 }, {
     width: number;
+    /**
+     * Whether the container has this view's body in the DOM.
+     *
+     * `ViewContainer` mounts a view's body only while an IntersectionObserver
+     * says it is on screen, to hold the app under the WebGL2 context ceiling
+     * (`reference/GPU_CONTEXT_BUDGET.md`). A view below the fold therefore has
+     * no canvas, so nothing ever calls `markCanvasDrawn` and the pre-first-paint
+     * term of `displayPhase` pins every display in it at `loading` with nothing
+     * left to resolve it — which parks `[data-app-phase="ready"]` for the whole
+     * app on a view the user cannot see.
+     *
+     * Defaults true so the containers that always mount a body — embedded
+     * views, workspace panels, and any test rendering a display directly — are
+     * unaffected and need not set it.
+     *
+     * The raw flag, written by this view's own container. A display asks
+     * `effectiveBodyMounted` instead, because a nested view has no container of
+     * its own.
+     */
+    bodyMounted: boolean;
 } & {
+    /**
+     * #getter
+     * Overridable hook (default true): whether this view's mounted body
+     * renders its own displays. A linear genome view collapsed to its ruler
+     * mounts the scalebar and none of its tracks, so a display in it can no
+     * more paint than one in a view scrolled off screen. Views nested in this
+     * one are unaffected: they paint wherever their own body is.
+     */
+    readonly rendersDisplays: boolean;
+    /**
+     * #getter
+     * Whether this view's displays have a canvas to paint into: its body is in
+     * the DOM, counting the views it is nested inside, and the body renders
+     * them (`rendersDisplays`). This is the question a display's phase asks.
+     *
+     * `bodyMounted` alone answers the DOM half only for a view a container
+     * renders directly. A view nested in another view (a synteny row, a
+     * breakpoint panel) has no container writing its flag, so it reads `true`
+     * forever while its whole subtree is out of the DOM, and every display in
+     * it waits for a first paint that nothing will make — the hang this flag
+     * exists to prevent, one level down.
+     *
+     * An ancestor that does not carry the flag at all leaves the answer alone
+     * rather than excusing the paint: only an explicit `false` unmounts, so a
+     * duck-typed stand-in that forgot it keeps waiting, which is the failure
+     * that shows up as a slow test rather than as a picture of an empty view.
+     */
+    readonly effectiveBodyMounted: boolean;
+    /**
+     * #method
+     */
     menuItems(): MenuItem[];
+    /**
+     * #getter
+     * The tracks this view puts in the census — its own, not a nested view's.
+     *
+     * Empty here, and overridden by the views that have any: the base cannot
+     * read `self.tracks` for them, because what a view keeps under that name
+     * is the view's business. react-msaview's holds its MSA annotation rows —
+     * `{ReactComponent, model}` objects with no configuration and no displays
+     * — and a base that helped itself to them handed them to the readiness
+     * marker as tracks, which error-paged every session holding an MSA view.
+     */
+    readonly ownTracks: AbstractTrackModel[];
+    /**
+     * #getter
+     * The views nested directly inside this one, which the census counts as
+     * views in their own right — a synteny stack's genome rows, a breakpoint
+     * split view's panels.
+     *
+     * Empty here for the same reason, and the dotplot is why it has to be a
+     * declaration rather than a walk of `views`: that prop name holds its two
+     * 1D *axis* models, which are view-shaped and are not views the user
+     * opened. No structural test separates the two — only the view knows.
+     */
+    readonly ownViews: AbstractViewModel[];
 } & {
+    /**
+     * #action
+     */
     setDisplayName(name: string): void;
+    /**
+     * #action
+     * width is an important attribute of the view model, when it becomes set,
+     * it often indicates when the app can start drawing to it. certain views
+     * like lgv are strict about this because if it tries to draw before it
+     * knows the width it should draw to, it may start fetching data for
+     * regions it doesn't need to
+     *
+     * setWidth is updated by a ResizeObserver generally, the views often need
+     * to know how wide they are to properly draw genomic regions
+     */
     setWidth(newWidth: number): void;
+    /**
+     * #action
+     * See `bodyMounted`. Written by the view's container, which is the only
+     * thing that knows whether it rendered the body.
+     */
+    setBodyMounted(flag: boolean): void;
+    /**
+     * #action
+     */
     setMinimized(flag: boolean): 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]>;
-    displayName: import("@jbrowse/mobx-state-tree").IMaybe<import("@jbrowse/mobx-state-tree").ISimpleType<string>>;
-    minimized: import("@jbrowse/mobx-state-tree").IType<boolean | undefined, boolean, boolean>;
-}>>;
+}, import("@jbrowse/mobx-state-tree")._NotCustomized, import("@jbrowse/mobx-state-tree")._NotCustomized>;
 export type IBaseViewModelWithDisplayedRegions = Instance<typeof BaseViewModelWithDisplayedRegions>;

package/esm/pluggableElementTypes/models/BaseViewModel.js

@@ -1,41 +1,179 @@
-import { types } from '@jbrowse/mobx-state-tree';
-import { ElementId, Region } from "../../util/types/mst.js";
-function x() { }
+import { getParent, hasParent, types } from '@jbrowse/mobx-state-tree';
+import { isViewModel } from '../../util/types/index.js';
+import { ElementId, Region } from '../../util/types/mst.js';
+/**
+ * The view a view is nested in, if it is nested in one at all — a synteny row
+ * inside its stack, a breakpoint panel inside its split view. `undefined` for
+ * the ordinary case of a view sitting directly in the session, and for a view
+ * not yet attached to a tree.
+ *
+ * `getContainingView` cannot answer this: it throws when there is no such
+ * ancestor, which here is the common case rather than an error.
+ */
+function containingViewOf(node) {
+    let current = node;
+    while (hasParent(current)) {
+        current = getParent(current);
+        if (isViewModel(current)) {
+            return current;
+        }
+    }
+    return undefined;
+}
+function bodyInDom(view) {
+    const parent = containingViewOf(view);
+    return (view.bodyMounted !== false && (parent === undefined || bodyInDom(parent)));
+}
+/**
+ * #stateModel BaseViewModel
+ * #category view
+ */
 const BaseViewModel = types
     .model('BaseView', {
+    /**
+     * #property
+     */
     id: ElementId,
+    /**
+     * #property
+     * displayName is displayed in the header of the view, or assembly names
+     * being used if none is specified
+     */
     displayName: types.maybe(types.string),
-    minimized: false,
+    /**
+     * #property
+     * collapse the view to its header bar, keeping it in the session rather
+     * than closing it
+     */
+    minimized: types.stripDefault(types.boolean, false),
 })
     .volatile(() => ({
     width: 800,
+    /**
+     * Whether the container has this view's body in the DOM.
+     *
+     * `ViewContainer` mounts a view's body only while an IntersectionObserver
+     * says it is on screen, to hold the app under the WebGL2 context ceiling
+     * (`reference/GPU_CONTEXT_BUDGET.md`). A view below the fold therefore has
+     * no canvas, so nothing ever calls `markCanvasDrawn` and the pre-first-paint
+     * term of `displayPhase` pins every display in it at `loading` with nothing
+     * left to resolve it — which parks `[data-app-phase="ready"]` for the whole
+     * app on a view the user cannot see.
+     *
+     * Defaults true so the containers that always mount a body — embedded
+     * views, workspace panels, and any test rendering a display directly — are
+     * unaffected and need not set it.
+     *
+     * The raw flag, written by this view's own container. A display asks
+     * `effectiveBodyMounted` instead, because a nested view has no container of
+     * its own.
+     */
+    bodyMounted: true,
 }))
-    .views(() => ({
+    .views(self => ({
+    /**
+     * #getter
+     * Overridable hook (default true): whether this view's mounted body
+     * renders its own displays. A linear genome view collapsed to its ruler
+     * mounts the scalebar and none of its tracks, so a display in it can no
+     * more paint than one in a view scrolled off screen. Views nested in this
+     * one are unaffected: they paint wherever their own body is.
+     */
+    get rendersDisplays() {
+        return true;
+    },
+    /**
+     * #getter
+     * Whether this view's displays have a canvas to paint into: its body is in
+     * the DOM, counting the views it is nested inside, and the body renders
+     * them (`rendersDisplays`). This is the question a display's phase asks.
+     *
+     * `bodyMounted` alone answers the DOM half only for a view a container
+     * renders directly. A view nested in another view (a synteny row, a
+     * breakpoint panel) has no container writing its flag, so it reads `true`
+     * forever while its whole subtree is out of the DOM, and every display in
+     * it waits for a first paint that nothing will make — the hang this flag
+     * exists to prevent, one level down.
+     *
+     * An ancestor that does not carry the flag at all leaves the answer alone
+     * rather than excusing the paint: only an explicit `false` unmounts, so a
+     * duck-typed stand-in that forgot it keeps waiting, which is the failure
+     * that shows up as a slow test rather than as a picture of an empty view.
+     */
+    get effectiveBodyMounted() {
+        return this.rendersDisplays && bodyInDom(self);
+    },
+    /**
+     * #method
+     */
     menuItems() {
         return [];
     },
+    /**
+     * #getter
+     * The tracks this view puts in the census — its own, not a nested view's.
+     *
+     * Empty here, and overridden by the views that have any: the base cannot
+     * read `self.tracks` for them, because what a view keeps under that name
+     * is the view's business. react-msaview's holds its MSA annotation rows —
+     * `{ReactComponent, model}` objects with no configuration and no displays
+     * — and a base that helped itself to them handed them to the readiness
+     * marker as tracks, which error-paged every session holding an MSA view.
+     */
+    get ownTracks() {
+        return [];
+    },
+    /**
+     * #getter
+     * The views nested directly inside this one, which the census counts as
+     * views in their own right — a synteny stack's genome rows, a breakpoint
+     * split view's panels.
+     *
+     * Empty here for the same reason, and the dotplot is why it has to be a
+     * declaration rather than a walk of `views`: that prop name holds its two
+     * 1D *axis* models, which are view-shaped and are not views the user
+     * opened. No structural test separates the two — only the view knows.
+     */
+    get ownViews() {
+        return [];
+    },
 }))
     .actions(self => ({
+    /**
+     * #action
+     */
     setDisplayName(name) {
         self.displayName = name;
     },
+    /**
+     * #action
+     * width is an important attribute of the view model, when it becomes set,
+     * it often indicates when the app can start drawing to it. certain views
+     * like lgv are strict about this because if it tries to draw before it
+     * knows the width it should draw to, it may start fetching data for
+     * regions it doesn't need to
+     *
+     * setWidth is updated by a ResizeObserver generally, the views often need
+     * to know how wide they are to properly draw genomic regions
+     */
     setWidth(newWidth) {
         self.width = newWidth;
     },
+    /**
+     * #action
+     * See `bodyMounted`. Written by the view's container, which is the only
+     * thing that knows whether it rendered the body.
+     */
+    setBodyMounted(flag) {
+        self.bodyMounted = flag;
+    },
+    /**
+     * #action
+     */
     setMinimized(flag) {
         self.minimized = flag;
     },
-}))
-    .postProcessSnapshot(snap => {
-    if (!snap) {
-        return snap;
-    }
-    const { minimized, ...rest } = snap;
-    return {
-        ...rest,
-        ...(minimized ? { minimized } : {}),
-    };
-});
+}));
 export default BaseViewModel;
 export const BaseViewModelWithDisplayedRegions = BaseViewModel.props({
     displayedRegions: types.array(Region),