@jbrowse/core 4.3.0 → 5.0.0-beta.2

package/esm/ui/sliderScale.js

@@ -0,0 +1,30 @@
+// Maps a real-unit value to/from a MUI Slider's internal thumb position for
+// non-linear controls, so callers pass real-unit min/max/value and read
+// real-unit values back. 'log' (log2 × 100) suits quantities spanning orders of
+// magnitude (bp window/step/length, read-support counts); 'cubic' gives fine
+// control near 0 where small changes read as large (opacity). `sliderStep` is
+// the step in slider space (undefined for linear — the caller supplies a
+// real-unit step). Single source for these transforms across the inline
+// track-menu sliders (makeSizeMenu) and the slider submenus behind
+// makeSizeSubMenu (the dotplot's and synteny's settings menus).
+export function sliderScale(scale) {
+    if (scale === 'log') {
+        return {
+            toSlider: (n) => Math.log2(Math.max(1, n)) * 100,
+            fromSlider: (v) => Math.round(2 ** (v / 100)),
+            sliderStep: 1,
+        };
+    }
+    if (scale === 'cubic') {
+        return {
+            toSlider: (n) => Math.cbrt(n),
+            fromSlider: (v) => v ** 3,
+            sliderStep: 0.01,
+        };
+    }
+    return {
+        toSlider: (n) => n,
+        fromSlider: (v) => v,
+        sliderStep: undefined,
+    };
+}

package/esm/ui/statusProgressKeyframes.d.ts

@@ -0,0 +1,6 @@
+export declare const indeterminateSweep: {
+    name: string;
+    styles: string;
+    anim: 1;
+    toString: () => string;
+} & string;

package/esm/ui/statusProgressKeyframes.js

@@ -0,0 +1,14 @@
+import { keyframes } from '../util/tss-react/index.js';
+// The indeterminate sweep. One bar rather than MUI's two: two say nothing the
+// first does not, and this one is drawn over work that is already saturating a
+// thread.
+//
+// `transform` alone, like `loadingDotKeyframes`, because the compositor owns it
+// — a `left` or `width` animation runs on the main thread and freezes during
+// exactly the jank this bar exists to explain. The bar is 40% of the track, so
+// -100% of its own width parks it clear of the left edge and 350% carries its
+// left edge past the right one.
+export const indeterminateSweep = keyframes `
+  from { transform: translateX(-100%); }
+  to { transform: translateX(350%); }
+`;

package/esm/ui/stripStackTraceMessage.d.ts

@@ -0,0 +1 @@
+export declare function stripStackTraceMessage(trace: string, message: string): string;

package/esm/ui/stripStackTraceMessage.js

@@ -0,0 +1,9 @@
+// Chrome prepends the error message to the stack trace; Firefox doesn't. Strip
+// it to avoid duplication (the message is already shown above the trace). The
+// message is the stringified error, e.g. "TypeError: foo" for any Error
+// subclass, so compare against it rather than a hardcoded "Error:" prefix.
+export function stripStackTraceMessage(trace, message) {
+    return message && trace.startsWith(message)
+        ? trace.slice(message.length)
+        : trace;
+}

package/esm/ui/styleTheme.d.ts

@@ -0,0 +1,158 @@
+import type { JBrowsePalette, ThemeInput } from './palette.ts';
+/**
+ * JBrowse's grid unit, in px. Half Material's 8, because a genome browser packs
+ * far more controls into a toolbar than a Material layout expects.
+ */
+export declare const DEFAULT_SPACING = 4;
+/** Base font size, in px. Material's default is 14; JBrowse's chrome is denser. */
+export declare const DEFAULT_FONT_SIZE = 12;
+/** What `pxToRem` assumes the `<html>` font size is. */
+export declare const HTML_FONT_SIZE = 16;
+export declare const DEFAULT_FONT_FAMILY = "\"Roboto\", \"Helvetica\", \"Arial\", sans-serif";
+export declare const DEFAULT_BORDER_RADIUS = 4;
+/**
+ * One entry of the type scale. `letterSpacing` is absent for a non-Roboto
+ * family rather than reset to `normal`, which is what MUI does and what lets a
+ * host's own tracking through.
+ */
+export interface TypeVariant {
+    fontFamily: string;
+    fontWeight: number | string;
+    fontSize: string;
+    lineHeight: number;
+    letterSpacing?: string;
+}
+export interface JBrowseTypography {
+    fontFamily: string;
+    fontSize: number;
+    htmlFontSize: number;
+    fontWeightLight: number | string;
+    fontWeightRegular: number | string;
+    fontWeightMedium: number | string;
+    fontWeightBold: number | string;
+    pxToRem: (size: number) => string;
+    body1: TypeVariant;
+    body2: TypeVariant;
+}
+/**
+ * What a `makeStyles` block is handed.
+ *
+ * Deliberately a subset of Material UI's `Theme` rather than a copy of it: it
+ * carries what the 268 call sites read and nothing else, so anything reaching
+ * further is a compile error naming the file rather than a silent dependency on
+ * a component library. `transitions`, `zIndex` and `shadows` are the three that
+ * used to be reached for; a literal reads better at each of those five sites,
+ * and `ui/zIndexes.ts` already owns the layering that matters.
+ */
+/**
+ * Where a portaled overlay is mounted. An element, a function returning one
+ * (which is what a shadow-DOM host writes, since its root does not exist when
+ * the config is built), or absent for `document.body`.
+ */
+export type PortalContainer = Element | (() => Element | null | undefined) | null | undefined;
+export interface JBrowseStyleTheme {
+    palette: JBrowsePalette;
+    spacing: (...args: number[]) => string;
+    shape: {
+        borderRadius: number;
+    };
+    typography: JBrowseTypography;
+    /**
+     * Where JBrowse's own portaled overlays mount. Read by `BaseTooltip`, which
+     * is the one piece of display chrome that has to escape its track's
+     * `contain: strict` box and so cannot render in place.
+     *
+     * It exists here so that reading it costs no UI toolkit. The tooltip used to
+     * take it off the Material theme (`useTheme().components.MuiPopper`), which
+     * put `@mui/material` in the import graph of a component every display
+     * renders on hover — including for a host that mounted `DisplayUIProvider`
+     * precisely to avoid that. Nothing Material was drawn, so neither half of
+     * jbrowse-build-your-own's census could see it: `Portal` emits no classed
+     * element, and the chip sets `fontFamily: inherit`, which is what defeats the
+     * Roboto fingerprint.
+     */
+    portalContainer?: PortalContainer;
+}
+export interface TypographyInput {
+    fontFamily?: string;
+    fontSize?: number;
+    htmlFontSize?: number;
+    fontWeightLight?: number | string;
+    fontWeightRegular?: number | string;
+    fontWeightMedium?: number | string;
+    fontWeightBold?: number | string;
+}
+/**
+ * The non-color half of what a theme may declare — `spacing` and `typography`,
+ * the two documented in the theming guide's "Sizing".
+ *
+ * Both admit a function arm, and that is not overbuilding: the config `theme`
+ * slot is typed as MUI's `ThemeOptions`, which has one, so this has to accept
+ * it for a caller to hand `themeOptions` straight in. Neither survives JSON, so
+ * neither reaches here from a config; `resolveStyleTheme` falls back to the
+ * defaults if one somehow does, rather than calling it.
+ */
+export interface SizingInput {
+    spacing?: number | string | readonly (number | string)[] | ((abs: never) => unknown);
+    typography?: TypographyInput | ((palette: never) => unknown);
+}
+/**
+ * A number is a grid unit and an array is a lookup table indexed by the
+ * argument, which is Material's contract and what a JSON config slot can
+ * express. An array entry that is already a string carries its own unit.
+ */
+export declare function createSpacing(input: SizingInput['spacing']): (...args: number[]) => string;
+export declare function createTypography(input?: TypographyInput): {
+    fontFamily: string;
+    fontSize: number;
+    htmlFontSize: number;
+    fontWeightLight: string | number;
+    fontWeightRegular: string | number;
+    fontWeightMedium: string | number;
+    fontWeightBold: string | number;
+    pxToRem: (size: number) => string;
+    body1: TypeVariant;
+    body2: TypeVariant;
+};
+/**
+ * The portal container, as a config theme states it.
+ *
+ * Deliberately the slot Material UI's own portaled components already read, so
+ * a shadow-DOM embed keeps stating it once and every portal — MUI's popovers
+ * and menus, and JBrowse's tooltip — lands in the same node. Moving JBrowse's
+ * tooltip off the Material theme was about its *import graph*, not about giving
+ * embedders a second thing to configure, so the vocabulary stays put.
+ */
+export interface PortalInput {
+    components?: {
+        MuiPopper?: {
+            defaultProps?: {
+                container?: PortalContainer;
+            };
+        };
+    };
+}
+/** A theme, as far as the style theme is concerned: colors plus sizing. */
+export interface StyleThemeInput extends ThemeInput, SizingInput, PortalInput {
+}
+/** What `resolveStyleTheme` reads — `resolvePalette`'s arguments, plus sizing. */
+export interface StyleThemeArgs {
+    configTheme?: StyleThemeInput;
+    themeName?: string;
+    extraThemes?: Record<string, StyleThemeInput>;
+}
+/**
+ * Build the style theme for a set of theme args.
+ *
+ * The colors come from `resolvePalette`, so this and the MUI theme cannot
+ * disagree about them by construction. Sizing follows the same rule the palette
+ * does: only the `default` theme draws from the config, since the named presets
+ * are fixed.
+ */
+export declare function resolveStyleTheme(args?: StyleThemeArgs): JBrowseStyleTheme;
+/**
+ * The style theme a component gets with no provider above it, resolved once
+ * rather than per call — a fresh object each render would defeat the
+ * memoization every `makeStyles` hook depends on.
+ */
+export declare const defaultStyleTheme: JBrowseStyleTheme;

package/esm/ui/styleTheme.js

@@ -0,0 +1,115 @@
+/**
+ * JBrowse's non-color design tokens, as plain data.
+ *
+ * `palette.ts` did this for color; this is the rest of what a `makeStyles`
+ * block reads — spacing, corner radius, the type scale — and it exists for the
+ * same reason. `makeStyles` used to take Material UI's `Theme`, which meant one
+ * six-line module (`util/tss-react/mui/mui.ts`) pulled `createTheme` into the
+ * first paint of every host, including one rendering a display that draws
+ * nothing Material at all. 268 call sites kept it there.
+ *
+ * The values below reproduce Material UI's, because they have to: JBrowse's own
+ * chrome *is* Material UI, and a `makeStyles` row sitting next to a `Typography`
+ * has to agree with it about what `body2` is. `styleTheme.test.ts` asserts that
+ * member by member against a real MUI theme, so a drift on an upgrade shows up
+ * as a test failure rather than as a slightly misaligned browser.
+ *
+ * `theme.ts` is the consumer, exactly as it is for the palette: it feeds these
+ * constants into `createTheme` rather than restating them.
+ */
+import { resolvePalette } from './palette.js';
+/**
+ * JBrowse's grid unit, in px. Half Material's 8, because a genome browser packs
+ * far more controls into a toolbar than a Material layout expects.
+ */
+export const DEFAULT_SPACING = 4;
+/** Base font size, in px. Material's default is 14; JBrowse's chrome is denser. */
+export const DEFAULT_FONT_SIZE = 12;
+/** What `pxToRem` assumes the `<html>` font size is. */
+export const HTML_FONT_SIZE = 16;
+export const DEFAULT_FONT_FAMILY = '"Roboto", "Helvetica", "Arial", sans-serif';
+export const DEFAULT_BORDER_RADIUS = 4;
+// MUI rounds letter-spacing to 5 decimal places; matched so the emitted `em`
+// value is character-identical to the one on a neighbouring Typography.
+function round(value) {
+    return Math.round(value * 1e5) / 1e5;
+}
+/**
+ * A number is a grid unit and an array is a lookup table indexed by the
+ * argument, which is Material's contract and what a JSON config slot can
+ * express. An array entry that is already a string carries its own unit.
+ */
+export function createSpacing(input) {
+    const step = Array.isArray(input) || typeof input === 'number' ? input : DEFAULT_SPACING;
+    const transform = (n) => {
+        const value = typeof step === 'number' ? n * step : step[n];
+        return typeof value === 'number' ? `${value}px` : (value ?? '');
+    };
+    return (...args) => (args.length === 0 ? [1] : args).map(transform).join(' ');
+}
+export function createTypography(input = {}) {
+    const { fontFamily = DEFAULT_FONT_FAMILY, fontSize = DEFAULT_FONT_SIZE, htmlFontSize = HTML_FONT_SIZE, fontWeightLight = 300, fontWeightRegular = 400, fontWeightMedium = 500, fontWeightBold = 700, } = input;
+    // Material's type scale is stated at fontSize 14 and scaled from there, so a
+    // theme that sets fontSize moves every variant with it.
+    const coef = fontSize / 14;
+    const pxToRem = (size) => `${(size / htmlFontSize) * coef}rem`;
+    // letterSpacing is only applied for the stock font: the values were designed
+    // for Roboto and carrying them onto another family throws off its kerning,
+    // which is MUI's rule and has to be this module's too.
+    const variant = (fontWeight, size, lineHeight, letterSpacing) => ({
+        fontFamily,
+        fontWeight,
+        fontSize: pxToRem(size),
+        lineHeight,
+        ...(fontFamily === DEFAULT_FONT_FAMILY
+            ? { letterSpacing: `${round(letterSpacing / size)}em` }
+            : {}),
+    });
+    return {
+        fontFamily,
+        fontSize,
+        htmlFontSize,
+        fontWeightLight,
+        fontWeightRegular,
+        fontWeightMedium,
+        fontWeightBold,
+        pxToRem,
+        body1: variant(fontWeightRegular, 16, 1.5, 0.15),
+        body2: variant(fontWeightRegular, 14, 1.43, 0.15),
+    };
+}
+/**
+ * Build the style theme for a set of theme args.
+ *
+ * The colors come from `resolvePalette`, so this and the MUI theme cannot
+ * disagree about them by construction. Sizing follows the same rule the palette
+ * does: only the `default` theme draws from the config, since the named presets
+ * are fixed.
+ */
+export function resolveStyleTheme(args = {}) {
+    const { configTheme, themeName = 'default', extraThemes } = args;
+    // only `extraThemes` is consulted for a preset: the built-in presets differ
+    // from each other in color and in Material component overrides, never in
+    // sizing, so there is nothing of theirs to read here
+    const preset = extraThemes?.[themeName] ?? {};
+    const sizing = themeName === 'default' ? { ...preset, ...configTheme } : preset;
+    const { typography } = sizing;
+    return {
+        palette: resolvePalette(args),
+        spacing: createSpacing(sizing.spacing),
+        shape: { borderRadius: DEFAULT_BORDER_RADIUS },
+        typography: createTypography(typeof typography === 'function' ? {} : typography),
+        // From `configTheme` rather than from `sizing`, and unconditionally rather
+        // than only for the default theme. A preset never states a portal
+        // container — it is a fact about where the app is mounted, not about how it
+        // looks — so a shadow-DOM embed that also picks a named theme must not lose
+        // its container to the preset merge that `sizing` performs.
+        portalContainer: configTheme?.components?.MuiPopper?.defaultProps?.container,
+    };
+}
+/**
+ * The style theme a component gets with no provider above it, resolved once
+ * rather than per call — a fresh object each render would defeat the
+ * memoization every `makeStyles` hook depends on.
+ */
+export const defaultStyleTheme = resolveStyleTheme();

package/esm/ui/submenuAim.d.ts

@@ -0,0 +1,30 @@
+export interface AimPoint {
+    x: number;
+    y: number;
+}
+export interface AimRect {
+    left: number;
+    right: number;
+    top: number;
+    bottom: number;
+}
+/**
+ * Whether a pointer at `point` is still on its way to `panel`.
+ *
+ * The region is a cone — a `<` lying open toward the panel — with its tip at
+ * `apex`, the spot the pointer was at when the panel opened, and its mouth the
+ * panel's whole near edge. Anywhere inside it the pointer is plausibly
+ * traveling to the panel, however many rows of the parent menu that path
+ * crosses; anywhere outside it the pointer is going somewhere else and the
+ * panel can shut at once.
+ *
+ * The cone widens with distance, which is what makes it better than a delay:
+ * one step off the parent row admits almost no vertical drift, while a pointer
+ * most of the way across admits the panel's full height. A pointer heading
+ * straight down the menu leaves it immediately at any speed, so nothing has to
+ * be waited out.
+ *
+ * `panel` is read in viewport coordinates, the same frame `apex` and `point`
+ * come from (`clientX`/`clientY`), so a scrolled page needs no correction.
+ */
+export declare function isAimedAtPanel(point: AimPoint, apex: AimPoint, panel: AimRect): boolean;

package/esm/ui/submenuAim.js

@@ -0,0 +1,37 @@
+/**
+ * Whether a pointer at `point` is still on its way to `panel`.
+ *
+ * The region is a cone — a `<` lying open toward the panel — with its tip at
+ * `apex`, the spot the pointer was at when the panel opened, and its mouth the
+ * panel's whole near edge. Anywhere inside it the pointer is plausibly
+ * traveling to the panel, however many rows of the parent menu that path
+ * crosses; anywhere outside it the pointer is going somewhere else and the
+ * panel can shut at once.
+ *
+ * The cone widens with distance, which is what makes it better than a delay:
+ * one step off the parent row admits almost no vertical drift, while a pointer
+ * most of the way across admits the panel's full height. A pointer heading
+ * straight down the menu leaves it immediately at any speed, so nothing has to
+ * be waited out.
+ *
+ * `panel` is read in viewport coordinates, the same frame `apex` and `point`
+ * come from (`clientX`/`clientY`), so a scrolled page needs no correction.
+ */
+export function isAimedAtPanel(point, apex, panel) {
+    // whichever vertical edge faces the tip: MUI flips a submenu to the other
+    // side of its row when the viewport has no room on the usual one
+    const nearX = Math.abs(panel.left - apex.x) <= Math.abs(panel.right - apex.x)
+        ? panel.left
+        : panel.right;
+    const toPanel = nearX - apex.x;
+    if (toPanel === 0) {
+        return true;
+    }
+    // how far across the gap the pointer has come, clamped so that a pointer
+    // beyond the near edge is judged against the panel's real extent rather than
+    // a cone that keeps widening past it
+    const crossed = Math.min((point.x - apex.x) / toPanel, 1);
+    return (crossed > 0 &&
+        point.y >= apex.y + (panel.top - apex.y) * crossed &&
+        point.y <= apex.y + (panel.bottom - apex.y) * crossed);
+}