@jbrowse/core 4.3.0 → 5.0.0-beta.2

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

@@ -1,52 +1,252 @@
 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
+     * Whether this view's body is in the DOM, counting the views it is nested
+     * inside — which is the question a display's phase actually asks.
+     *
+     * `bodyMounted` alone answers it 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
+     * Every track open on this view itself: its own `tracks` array plus any
+     * track containers it owns instead (the synteny view keeps one list per
+     * band on `trackContainers` and its own `tracks` empty). Tracks on nested
+     * views are `allTracks`'s, not this getter's.
+     */
+    readonly ownTracks: AbstractTrackModel[];
+    /**
+     * #getter
+     * This view and every view nested inside it, to any depth — a synteny
+     * stack's genome rows, a breakpoint split view's panels. Each view answers
+     * for its own children, so a consumer never walks the nesting itself:
+     * before this getter, four consumers each carried a copy of the walk and
+     * two of them had drifted (one read `levels`, one read `trackContainers`,
+     * and each was blind to the other's spelling).
+     */
+    readonly allViews: AbstractViewModel[];
 } & {
+    /**
+     * #getter
+     * Every track open on this view or any view nested inside it.
+     */
+    readonly allTracks: AbstractTrackModel[];
+} & {
+    /**
+     * #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
+     * Whether this view's body is in the DOM, counting the views it is nested
+     * inside — which is the question a display's phase actually asks.
+     *
+     * `bodyMounted` alone answers it 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
+     * Every track open on this view itself: its own `tracks` array plus any
+     * track containers it owns instead (the synteny view keeps one list per
+     * band on `trackContainers` and its own `tracks` empty). Tracks on nested
+     * views are `allTracks`'s, not this getter's.
+     */
+    readonly ownTracks: AbstractTrackModel[];
+    /**
+     * #getter
+     * This view and every view nested inside it, to any depth — a synteny
+     * stack's genome rows, a breakpoint split view's panels. Each view answers
+     * for its own children, so a consumer never walks the nesting itself:
+     * before this getter, four consumers each carried a copy of the walk and
+     * two of them had drifted (one read `levels`, one read `trackContainers`,
+     * and each was blind to the other's spelling).
+     */
+    readonly allViews: AbstractViewModel[];
 } & {
+    /**
+     * #getter
+     * Every track open on this view or any view nested inside it.
+     */
+    readonly allTracks: AbstractTrackModel[];
+} & {
+    /**
+     * #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,175 @@
-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;
+}
+/**
+ * #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
+     * Whether this view's body is in the DOM, counting the views it is nested
+     * inside — which is the question a display's phase actually asks.
+     *
+     * `bodyMounted` alone answers it 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 (self.bodyMounted &&
+            containingViewOf(self)?.effectiveBodyMounted !== false);
+    },
+    /**
+     * #method
+     */
     menuItems() {
         return [];
     },
+    /**
+     * #getter
+     * Every track open on this view itself: its own `tracks` array plus any
+     * track containers it owns instead (the synteny view keeps one list per
+     * band on `trackContainers` and its own `tracks` empty). Tracks on nested
+     * views are `allTracks`'s, not this getter's.
+     */
+    get ownTracks() {
+        const s = self;
+        return [
+            ...(s.tracks ?? []),
+            ...(s.trackContainers ?? []).flatMap(c => c.tracks ?? []),
+        ];
+    },
+    /**
+     * #getter
+     * This view and every view nested inside it, to any depth — a synteny
+     * stack's genome rows, a breakpoint split view's panels. Each view answers
+     * for its own children, so a consumer never walks the nesting itself:
+     * before this getter, four consumers each carried a copy of the walk and
+     * two of them had drifted (one read `levels`, one read `trackContainers`,
+     * and each was blind to the other's spelling).
+     */
+    get allViews() {
+        const s = self;
+        return [
+            self,
+            ...(s.views ?? []).flatMap(v => v.allViews ?? []),
+        ];
+    },
+}))
+    .views(self => ({
+    /**
+     * #getter
+     * Every track open on this view or any view nested inside it.
+     */
+    get allTracks() {
+        return self.allViews.flatMap(v => v.ownTracks);
+    },
 }))
     .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),

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

@@ -0,0 +1,51 @@
+import type { HighlightType } from '../../util/highlights.ts';
+/**
+ * #stateModel HighlightsMixin
+ * #category view
+ *
+ * The `view.highlight` band state shared verbatim by the LinearGenomeView and
+ * DotplotView: an array of translucent highlight regions plus the
+ * `showHighlightChips` toggle for their interactive chips. Both views compose
+ * this so the props and actions stay identical by construction rather than by
+ * two hand-kept copies. Visibility across all views is the session-wide
+ * `highlightsVisible` flag (on BaseSession), not a prop here.
+ */
+export default function HighlightsMixin(): import("@jbrowse/mobx-state-tree").IModelType<{
+    /**
+     * #property
+     * translucent highlight bands, seeded from URL params or session JSON and
+     * added interactively via the rubber-band menu
+     */
+    highlight: import("@jbrowse/mobx-state-tree").IOptionalIType<import("@jbrowse/mobx-state-tree").IArrayType<import("@jbrowse/mobx-state-tree").IType<HighlightType, HighlightType, HighlightType>>, [undefined]>;
+    /**
+     * #property
+     * pins the interactive highlight chip (link icon + context menu) to every
+     * highlight band; off by default, where a band instead reveals its chip
+     * while the pointer is in it. This is what a screenshot needs, since
+     * nothing hovers in one
+     */
+    showHighlightChips: import("@jbrowse/mobx-state-tree").IOptionalIType<import("@jbrowse/mobx-state-tree").ISimpleType<boolean>, [undefined]>;
+}, {
+    /**
+     * #action
+     */
+    addToHighlights(highlight: HighlightType): void;
+    /**
+     * #action
+     */
+    setHighlight(highlight?: HighlightType[]): void;
+    /**
+     * #action
+     */
+    removeHighlight(highlight: HighlightType): void;
+    /**
+     * #action
+     */
+    updateHighlight(old: HighlightType, updates: Partial<HighlightType>): void;
+    /**
+     * #action
+     */
+    setShowHighlightChips(arg: boolean): void;
+} & {
+    afterAttach(): void;
+}, import("@jbrowse/mobx-state-tree")._NotCustomized, import("@jbrowse/mobx-state-tree")._NotCustomized>;

package/esm/pluggableElementTypes/models/HighlightsMixin.js

@@ -0,0 +1,78 @@
+import { cast, types } from '@jbrowse/mobx-state-tree';
+import { revealHighlightsOnGrowth } from '../../util/highlights.js';
+import { getSession } from '../../util/index.js';
+/**
+ * #stateModel HighlightsMixin
+ * #category view
+ *
+ * The `view.highlight` band state shared verbatim by the LinearGenomeView and
+ * DotplotView: an array of translucent highlight regions plus the
+ * `showHighlightChips` toggle for their interactive chips. Both views compose
+ * this so the props and actions stay identical by construction rather than by
+ * two hand-kept copies. Visibility across all views is the session-wide
+ * `highlightsVisible` flag (on BaseSession), not a prop here.
+ */
+export default function HighlightsMixin() {
+    return types
+        .model({
+        /**
+         * #property
+         * translucent highlight bands, seeded from URL params or session JSON and
+         * added interactively via the rubber-band menu
+         */
+        highlight: types.stripDefault(types.array(types.frozen()), []),
+        /**
+         * #property
+         * pins the interactive highlight chip (link icon + context menu) to every
+         * highlight band; off by default, where a band instead reveals its chip
+         * while the pointer is in it. This is what a screenshot needs, since
+         * nothing hovers in one
+         */
+        showHighlightChips: types.stripDefault(types.boolean, false),
+    })
+        .actions(self => ({
+        /**
+         * #action
+         */
+        addToHighlights(highlight) {
+            self.highlight.push(highlight);
+        },
+        /**
+         * #action
+         */
+        setHighlight(highlight) {
+            self.highlight = cast(highlight);
+        },
+        /**
+         * #action
+         */
+        removeHighlight(highlight) {
+            self.highlight.remove(highlight);
+        },
+        /**
+         * #action
+         */
+        updateHighlight(old, updates) {
+            const idx = self.highlight.indexOf(old);
+            if (idx !== -1) {
+                self.highlight[idx] = { ...old, ...updates };
+                // reachable from the highlight grid, which lists entries even with
+                // the bands off, so recoloring there would otherwise do nothing
+                // visible. Not a growth, so revealHighlightsOnGrowth can't see it
+                getSession(self).revealHighlights();
+            }
+        },
+        /**
+         * #action
+         */
+        setShowHighlightChips(arg) {
+            self.showHighlightChips = arg;
+        },
+    }))
+        .actions(self => ({
+        afterAttach() {
+            // covers the rubber-band menu, dotplot drag and URL init alike
+            revealHighlightsOnGrowth(self, () => self.highlight.length);
+        },
+    }));
+}