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

package/esm/Session/Themes.d.ts

@@ -1,18 +1,152 @@
 import type PluginManager from '@jbrowse/core/PluginManager';
+import type { PaletteMode } from '@jbrowse/core/ui/palette';
+import type { SerializableThemeArgs, ThemeMap } from '@jbrowse/core/ui/theme';
 import type { IAnyStateTreeNode, Instance } from '@jbrowse/mobx-state-tree';
 import type { ThemeOptions } from '@mui/material';
-type ThemeMap = Record<string, ThemeOptions>;
+/** The three the mode picker offers; `system` follows the OS preference. */
+export type ThemeModeSelection = PaletteMode | 'system';
+/**
+ * The theme the stored selection resolves to, for UI drawn before a session
+ * exists, such as Desktop's start screen.
+ */
+export declare function storedThemeArgs(): SerializableThemeArgs;
+/**
+ * #stateModel ThemeManagerSessionMixin
+ */
 export declare function ThemeManagerSessionMixin(_pluginManager: PluginManager): import("@jbrowse/mobx-state-tree").IModelType<{}, {
     sessionThemeName: string;
+    sessionThemeMode: ThemeModeSelection;
+    systemThemeOverride: PaletteMode | undefined;
+    systemPrefersDark: boolean;
 } & {
+    /**
+     * #method
+     */
     allThemes(): ThemeMap;
+    /**
+     * #getter
+     * Which palette is in effect. A stored name whose theme an admin has
+     * since dropped reads as `default` without the stored value being
+     * touched, so it comes back if the plugin supplying it loads again.
+     */
     readonly themeName: string;
+    /**
+     * #getter
+     * Light, dark, or following the OS — the axis the palette is drawn
+     * along, and what the mode picker shows. `effectiveThemeMode` is the
+     * one to read for a colour decision.
+     */
+    readonly themeMode: ThemeModeSelection;
+    /**
+     * #getter
+     * Light or dark, with `system` resolved against the OS preference or
+     * the toolbar's hold on the other mode.
+     */
+    readonly effectiveThemeMode: PaletteMode;
+    /**
+     * #getter
+     * Whether what is drawn right now is dark. Read off the resolved
+     * palette rather than the mode, so a palette pinned to one mode — an
+     * `extraThemes` entry declaring `mode: 'dark'` — answers for itself.
+     */
+    readonly themeIsDark: boolean;
+    /**
+     * #getter
+     */
+    readonly themeOptions: SerializableThemeArgs;
+    /**
+     * #getter
+     * Every color JBrowse renders, resolved to plain strings. This is what
+     * rendering reads: it needs no React context, it crosses the RPC worker
+     * boundary as itself, and it costs no UI toolkit. Prefer it over
+     * `theme` anywhere the answer wanted is a color rather than a Material
+     * UI component style.
+     */
+    readonly palette: import("@jbrowse/core/ui/palette").JBrowsePalette;
+    /**
+     * #getter
+     * The palette plus the sizing tokens `makeStyles` reads — spacing,
+     * corner radius, type scale. This is what a product mounts on
+     * `StyleThemeProvider`; it costs no UI toolkit, and it is derived from
+     * the same `themeOptions` as `theme`, so a config `theme` that sets
+     * `spacing` moves JBrowse's own styles and its Material components
+     * together.
+     */
+    readonly styleTheme: import("@jbrowse/core/ui/styleTheme").JBrowseStyleTheme;
+    /**
+     * #getter
+     * The Material UI theme, for the components that are Material UI. Its
+     * palette is spliced from the same `resolvePalette` call as `palette`
+     * above, so the two cannot disagree.
+     */
     readonly theme: import("@mui/material").Theme;
+    /**
+     * #method
+     * Raw `ThemeOptions` for the active theme, or a named override (used by
+     * the SVG-export theme picker). Unlike `theme` (a built,
+     * non-serializable MUI theme), this is the plain options object every
+     * view's SVG export threads into each display's `renderSvg`, which
+     * rebuilds the theme via `createJBrowseTheme` outside React context.
+     *
+     * The `default` entry is merged with the config `theme` slot, because
+     * the picker labels it "Default (from config)" and `resolvePalette`
+     * merges the preset with the slot for every other consumer. The bare
+     * preset would make `view.exportSvg()` drop a host's configured
+     * palette: a config setting `primary.main` would draw `#123456` on
+     * screen and export the stock `#0D233F`, while the export dialog named
+     * the default theme. Every other named theme is a fixed preset that
+     * ignores config.
+     *
+     * **The mode is spliced in here**, because a palette no longer carries
+     * one and this is the last point before the export leaves the session:
+     * every caller hands `renderSvg` these options and nothing else, so a
+     * figure exported from a dark session comes out dark. A palette pinned
+     * to its own mode, or a `name` from before the axis, states the mode
+     * itself and keeps it.
+     */
+    getActiveThemeOptions(name?: string): ThemeOptions;
 } & {
+    /**
+     * #action
+     * Pick a palette. A name from before light and dark were an axis sets
+     * the mode it spelled as well, so an old share link, a saved figure spec
+     * and `jbrowse-img --theme darkStock` all still mean what they said.
+     * Either that or a palette pinned to its own mode drops a held mode,
+     * which would otherwise resurface on the next palette change.
+     */
     setThemeName(name: string): void;
+    /**
+     * #action
+     */
+    setSystemPrefersDark(dark: boolean): void;
+    /**
+     * #action
+     * Hold a session that follows the system on the mode the OS is not
+     * asking for, or `undefined` to follow it again. The toolbar's sun/moon
+     * writes this, so it stays in the toolbar after a click. The OS flipping
+     * clears it, since by then the OS has come round to the held mode. The
+     * palette is untouched: a reader on Minimal who does this keeps Minimal.
+     */
+    setSystemThemeOverride(mode?: PaletteMode): void;
+    /**
+     * #action
+     * Draw the session light or dark, leaving the palette alone. `system`
+     * follows the OS preference. Satisfies `ThemeModeSession`, so
+     * `useSessionPalette` works against an app session and an embedded one
+     * alike, and a host that follows its own dark-mode state calls this.
+     *
+     * `themeOptions` carries the mode to the RPC worker, so the labels baked
+     * into a rendered image follow it along with what React draws. That used
+     * to take a write into the config `theme` slot, because mode lived
+     * inside a palette and there was nowhere else to put it.
+     */
+    setThemeMode(mode: ThemeModeSelection): void;
+} & {
     afterAttach(): void;
 }, import("@jbrowse/mobx-state-tree")._NotCustomized, import("@jbrowse/mobx-state-tree")._NotCustomized>;
+/** Session mixin MST type for a session that supports theming */
 export type SessionWithThemesType = ReturnType<typeof ThemeManagerSessionMixin>;
+/** Instance of a session that has theming support */
 export type SessionWithThemes = Instance<SessionWithThemesType>;
+/** Type guard for SessionWithThemes */
 export declare function isSessionWithThemes(session: IAnyStateTreeNode): session is SessionWithThemes;
-export {};

package/esm/Session/Themes.js

@@ -1,43 +1,289 @@
 import { getConf } from '@jbrowse/core/configuration';
-import { createJBrowseTheme, defaultThemes } from '@jbrowse/core/ui';
+import { resolvePalette, resolveThemeSelection } from '@jbrowse/core/ui/palette';
+import { resolveStyleTheme } from '@jbrowse/core/ui/styleTheme';
+import { createJBrowseThemeFromArgs, defaultThemes, } from '@jbrowse/core/ui/theme';
 import { localStorageGetItem, localStorageSetItem } from '@jbrowse/core/util';
+import { onColorSchemeChange, prefersDarkColorScheme, } from '@jbrowse/core/util/systemColorScheme';
 import { addDisposer, types } from '@jbrowse/mobx-state-tree';
 import { autorun } from 'mobx';
+import { asSession } from '../siblingCast.js';
+import { isBaseSession } from './BaseSession.js';
+/**
+ * What `name` actually resolves to — `default` for one `themes` no longer
+ * holds. Every theme name is either stored or handed in from outside, and both
+ * go stale the same way: `sessionThemeName` outlives an `extraThemes` entry an
+ * admin drops, and so does a name an export dialog persisted or a saved figure
+ * spec carries.
+ */
+function resolveThemeName(themes, name) {
+    return themes[name] ? name : 'default';
+}
+/**
+ * A session starts light, and follows the OS only when asked to. A dark OS is
+ * not a request for a dark genome browser.
+ */
+const DEFAULT_MODE = 'light';
+function systemMode() {
+    return prefersDarkColorScheme() ? 'dark' : 'light';
+}
+// An override outlives a reload only while the OS still disagrees with it; one
+// the OS has since come round to means following again.
+function storedOverride() {
+    const stored = localStorageGetItem('themeModeOverride');
+    return (stored === 'light' || stored === 'dark') && stored !== systemMode()
+        ? stored
+        : undefined;
+}
+// A `themeName` stored before light and dark were an axis spells a mode into
+// the name. Split it once, on the way in, so the session persists the pair from
+// then on and the retired name goes away; a name this does not know — an
+// `extraThemes` entry whose plugin is absent — passes through untouched.
+function storedSelection() {
+    const stored = localStorageGetItem('themeName') ?? 'default';
+    const { themeName, mode } = resolveThemeSelection(stored);
+    const storedMode = localStorageGetItem('themeMode');
+    return {
+        sessionThemeName: themeName,
+        sessionThemeMode: storedMode ?? mode ?? DEFAULT_MODE,
+        systemThemeOverride: storedOverride(),
+    };
+}
+/**
+ * The theme the stored selection resolves to, for UI drawn before a session
+ * exists, such as Desktop's start screen.
+ */
+export function storedThemeArgs() {
+    const { sessionThemeName, sessionThemeMode, systemThemeOverride } = storedSelection();
+    return {
+        themeName: sessionThemeName,
+        mode: sessionThemeMode === 'system'
+            ? (systemThemeOverride ?? systemMode())
+            : sessionThemeMode,
+    };
+}
+/**
+ * #stateModel ThemeManagerSessionMixin
+ */
 export function ThemeManagerSessionMixin(_pluginManager) {
     return types
         .model({})
         .volatile(() => ({
-        sessionThemeName: localStorageGetItem('themeName') || 'default',
+        ...storedSelection(),
+        systemPrefersDark: prefersDarkColorScheme(),
     }))
-        .views(s => ({
-        allThemes() {
-            const self = s;
-            const extraThemes = getConf(self.jbrowse, 'extraThemes');
-            return { ...defaultThemes, ...extraThemes };
+        .views(s => {
+        const self = asSession(s);
+        return {
+            /**
+             * #method
+             */
+            allThemes() {
+                const extraThemes = getConf(self.jbrowse, 'extraThemes');
+                return { ...defaultThemes, ...extraThemes };
+            },
+            /**
+             * #getter
+             * Which palette is in effect. A stored name whose theme an admin has
+             * since dropped reads as `default` without the stored value being
+             * touched, so it comes back if the plugin supplying it loads again.
+             */
+            get themeName() {
+                return resolveThemeName(this.allThemes(), self.sessionThemeName);
+            },
+            /**
+             * #getter
+             * Light, dark, or following the OS — the axis the palette is drawn
+             * along, and what the mode picker shows. `effectiveThemeMode` is the
+             * one to read for a colour decision.
+             */
+            get themeMode() {
+                return self.sessionThemeMode;
+            },
+            /**
+             * #getter
+             * Light or dark, with `system` resolved against the OS preference or
+             * the toolbar's hold on the other mode.
+             */
+            get effectiveThemeMode() {
+                return this.themeMode === 'system'
+                    ? (self.systemThemeOverride ??
+                        (self.systemPrefersDark ? 'dark' : 'light'))
+                    : this.themeMode;
+            },
+            /**
+             * #getter
+             * Whether what is drawn right now is dark. Read off the resolved
+             * palette rather than the mode, so a palette pinned to one mode — an
+             * `extraThemes` entry declaring `mode: 'dark'` — answers for itself.
+             */
+            get themeIsDark() {
+                return this.palette.mode === 'dark';
+            },
+            /**
+             * #getter
+             */
+            // Structurally-serializable description of the active theme, safe to
+            // send across the RPC worker boundary (the created `theme` carries
+            // functions and cannot be cloned). The worker rebuilds via
+            // createJBrowseThemeFromArgs.
+            get themeOptions() {
+                return {
+                    configTheme: getConf(self.jbrowse, 'theme'),
+                    extraThemes: getConf(self.jbrowse, 'extraThemes'),
+                    themeName: this.themeName,
+                    mode: this.effectiveThemeMode,
+                };
+            },
+            /**
+             * #getter
+             * Every color JBrowse renders, resolved to plain strings. This is what
+             * rendering reads: it needs no React context, it crosses the RPC worker
+             * boundary as itself, and it costs no UI toolkit. Prefer it over
+             * `theme` anywhere the answer wanted is a color rather than a Material
+             * UI component style.
+             */
+            get palette() {
+                return resolvePalette(this.themeOptions);
+            },
+            /**
+             * #getter
+             * The palette plus the sizing tokens `makeStyles` reads — spacing,
+             * corner radius, type scale. This is what a product mounts on
+             * `StyleThemeProvider`; it costs no UI toolkit, and it is derived from
+             * the same `themeOptions` as `theme`, so a config `theme` that sets
+             * `spacing` moves JBrowse's own styles and its Material components
+             * together.
+             */
+            get styleTheme() {
+                return resolveStyleTheme(this.themeOptions);
+            },
+            /**
+             * #getter
+             * The Material UI theme, for the components that are Material UI. Its
+             * palette is spliced from the same `resolvePalette` call as `palette`
+             * above, so the two cannot disagree.
+             */
+            get theme() {
+                return createJBrowseThemeFromArgs(this.themeOptions);
+            },
+            /**
+             * #method
+             * Raw `ThemeOptions` for the active theme, or a named override (used by
+             * the SVG-export theme picker). Unlike `theme` (a built,
+             * non-serializable MUI theme), this is the plain options object every
+             * view's SVG export threads into each display's `renderSvg`, which
+             * rebuilds the theme via `createJBrowseTheme` outside React context.
+             *
+             * The `default` entry is merged with the config `theme` slot, because
+             * the picker labels it "Default (from config)" and `resolvePalette`
+             * merges the preset with the slot for every other consumer. The bare
+             * preset would make `view.exportSvg()` drop a host's configured
+             * palette: a config setting `primary.main` would draw `#123456` on
+             * screen and export the stock `#0D233F`, while the export dialog named
+             * the default theme. Every other named theme is a fixed preset that
+             * ignores config.
+             *
+             * **The mode is spliced in here**, because a palette no longer carries
+             * one and this is the last point before the export leaves the session:
+             * every caller hands `renderSvg` these options and nothing else, so a
+             * figure exported from a dark session comes out dark. A palette pinned
+             * to its own mode, or a `name` from before the axis, states the mode
+             * itself and keeps it.
+             */
+            getActiveThemeOptions(name) {
+                const all = this.allThemes();
+                const selection = resolveThemeSelection(name ?? this.themeName, undefined, all);
+                const themeName = resolveThemeName(all, selection.themeName);
+                const theme = all[themeName];
+                const mode = theme?.palette?.mode ?? selection.mode ?? this.effectiveThemeMode;
+                if (themeName !== 'default') {
+                    return { ...theme, palette: { ...theme?.palette, mode } };
+                }
+                // shallow over the palette, which is how `resolvePalette` spreads the
+                // same two — `mode` and `primary` are siblings there, so both levels
+                // have to survive
+                const configTheme = getConf(self.jbrowse, 'theme');
+                return {
+                    ...theme,
+                    ...configTheme,
+                    palette: { ...theme?.palette, ...configTheme.palette, mode },
+                };
+            },
+        };
+    })
+        .actions(self => ({
+        /**
+         * #action
+         * Pick a palette. A name from before light and dark were an axis sets
+         * the mode it spelled as well, so an old share link, a saved figure spec
+         * and `jbrowse-img --theme darkStock` all still mean what they said.
+         * Either that or a palette pinned to its own mode drops a held mode,
+         * which would otherwise resurface on the next palette change.
+         */
+        setThemeName(name) {
+            const { themeName, mode } = resolveThemeSelection(name);
+            self.sessionThemeName = themeName;
+            if (mode) {
+                self.sessionThemeMode = mode;
+            }
+            const drawnMode = self.themeIsDark ? 'dark' : 'light';
+            if (mode || drawnMode !== self.effectiveThemeMode) {
+                self.systemThemeOverride = undefined;
+            }
+        },
+        /**
+         * #action
+         */
+        setSystemPrefersDark(dark) {
+            if (dark !== self.systemPrefersDark) {
+                self.systemThemeOverride = undefined;
+            }
+            self.systemPrefersDark = dark;
         },
-        get themeName() {
-            const { sessionThemeName } = s;
-            const all = this.allThemes();
-            return all[sessionThemeName] ? sessionThemeName : 'default';
+        /**
+         * #action
+         * Hold a session that follows the system on the mode the OS is not
+         * asking for, or `undefined` to follow it again. The toolbar's sun/moon
+         * writes this, so it stays in the toolbar after a click. The OS flipping
+         * clears it, since by then the OS has come round to the held mode. The
+         * palette is untouched: a reader on Minimal who does this keeps Minimal.
+         */
+        setSystemThemeOverride(mode) {
+            self.systemThemeOverride = mode;
         },
-        get theme() {
-            const self = s;
-            const configTheme = getConf(self.jbrowse, 'theme');
-            const all = this.allThemes();
-            return createJBrowseTheme(configTheme, all, this.themeName);
+        /**
+         * #action
+         * Draw the session light or dark, leaving the palette alone. `system`
+         * follows the OS preference. Satisfies `ThemeModeSession`, so
+         * `useSessionPalette` works against an app session and an embedded one
+         * alike, and a host that follows its own dark-mode state calls this.
+         *
+         * `themeOptions` carries the mode to the RPC worker, so the labels baked
+         * into a rendered image follow it along with what React draws. That used
+         * to take a write into the config `theme` slot, because mode lived
+         * inside a palette and there was nowhere else to put it.
+         */
+        setThemeMode(mode) {
+            self.sessionThemeMode = mode;
+            self.systemThemeOverride = undefined;
         },
     }))
         .actions(self => ({
-        setThemeName(name) {
-            self.sessionThemeName = name;
-        },
         afterAttach() {
+            addDisposer(self, onColorSchemeChange(() => {
+                self.setSystemPrefersDark(prefersDarkColorScheme());
+            }));
             addDisposer(self, autorun(function themeNameAutorun() {
-                localStorageSetItem('themeName', self.themeName);
+                // persist the raw selection, not the coerced themeName, so a
+                // theme registered later isn't clobbered with 'default'
+                localStorageSetItem('themeName', self.sessionThemeName);
+                localStorageSetItem('themeMode', self.sessionThemeMode);
+                localStorageSetItem('themeModeOverride', self.systemThemeOverride ?? '');
             }, { name: 'ThemeName' }));
         },
     }));
 }
+/** Type guard for SessionWithThemes */
 export function isSessionWithThemes(session) {
-    return 'theme' in session;
+    return isBaseSession(session) && 'theme' in session;
 }

package/esm/Session/TrackMenu.d.ts

@@ -0,0 +1,88 @@
+import type PluginManager from '@jbrowse/core/PluginManager';
+import type { AnyConfigurationModel } from '@jbrowse/core/configuration';
+import type { BaseTrackConfig } from '@jbrowse/core/pluggableElementTypes';
+import type { MenuItem } from '@jbrowse/core/ui';
+import type { DialogComponentType } from '@jbrowse/core/util';
+import type { TrackActionView } from '@jbrowse/core/util/types';
+interface TrackActionSession<C> {
+    editConfiguration: (config: AnyConfigurationModel | {
+        trackId: string;
+    }, opts?: {
+        expandedDisplayId?: string;
+    }) => void;
+    publishTrackConf: (conf: C) => unknown;
+    deleteTrackConf: (conf: AnyConfigurationModel) => void;
+    resetTrackConfiguration?: (trackId: string) => void;
+    /**
+     * Declared here, though only the copy guard below reads it, so a session that
+     * loses the list loses the guard *loudly*. `namesTemporaryAssembly` takes an
+     * `unknown` session and answers false for one that holds no such list, which
+     * is right for a caller that genuinely has none and wrong for one that let it
+     * drop — and that second case is a copy action silently offered again.
+     *
+     * `unknown[]`, the spelling `AbstractSessionModel` already uses, and not the
+     * `{ name?: string }[]` the guard narrows to: that one is a weak type, so a
+     * real MST array of assembly configs — whose element type is an index
+     * signature that declares no `name` — shares no property with it and TS
+     * rejects the assignment. The shape belongs in the guard, which is the only
+     * thing that reads it.
+     */
+    temporaryAssemblies?: unknown[];
+}
+/**
+ * The shared Settings / Copy / Copy-and-open / Delete track actions. Each
+ * product supplies `makeCopy` (its own session-track/category rules) and
+ * `canEdit`; reference sequence tracks can't be copied or deleted. When
+ * `isSessionOverride` is set the track carries session edits over its base
+ * config, so a Reset is offered, and it replaces Delete for a user who cannot
+ * delete the base.
+ */
+export declare function trackActionItems<C extends {
+    trackId: string;
+}>({ session, config, view, canEdit, isSessionOverride, makeCopy, }: {
+    session: TrackActionSession<C>;
+    config: BaseTrackConfig;
+    view?: TrackActionView;
+    canEdit: boolean;
+    isSessionOverride?: boolean;
+    makeCopy: () => C;
+}): MenuItem[];
+export interface SessionWithDialog {
+    queueDialog: (cb: (done: () => void) => [DialogComponentType, Record<string, unknown>]) => void;
+}
+type TrackConfig = AnyConfigurationModel | Record<string, unknown>;
+/** "About track" menu item, shared by every product's track menu */
+export declare function aboutTrackMenuItem(session: SessionWithDialog, config: TrackConfig): MenuItem;
+/**
+ * flattened track menu (About + raw actions) for the hierarchical track selector
+ */
+export declare function trackListMenuItems(session: SessionWithDialog, config: TrackConfig, actions: MenuItem[]): MenuItem[];
+/**
+ * track menu with an "About track" item and a "Track actions" submenu, for the
+ * in-view track label menu
+ */
+export declare function trackActionMenuItems(session: SessionWithDialog, config: TrackConfig, actions: MenuItem[]): MenuItem[];
+/**
+ * #stateModel TrackMenuItemsSessionMixin
+ *
+ * The two track-menu wrappers (`getTrackListMenuItems` for the hierarchical
+ * selector, `getTrackActionMenuItems` for the in-view label menu) shared by the
+ * full web and desktop sessions. Both are pure functions of `getTrackActions`,
+ * which each session supplies (web gates on edit rights; desktop adds indexing).
+ */
+export declare function TrackMenuItemsSessionMixin(pluginManager: PluginManager): import("@jbrowse/mobx-state-tree").IModelType<{}, {
+    /**
+     * #method
+     * flattened menu items for use in hierarchical track selector
+     */
+    getTrackListMenuItems(config: BaseTrackConfig, view?: TrackActionView): MenuItem[];
+    /**
+     * #method
+     * track menu with About + "Track actions" submenu for the in-view label
+     */
+    getTrackActionMenuItems({ config, view, }: {
+        config: BaseTrackConfig;
+        view?: TrackActionView;
+    }): MenuItem[];
+}, import("@jbrowse/mobx-state-tree")._NotCustomized, import("@jbrowse/mobx-state-tree")._NotCustomized>;
+export {};