@jbrowse/core 4.3.0 → 5.0.0-beta.10

package/esm/ui/LoadingProgress.js

@@ -0,0 +1,16 @@
+import { Fragment as _Fragment, jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { progressLabel } from '../util/progress.js';
+import LoadingEllipses from './LoadingEllipses.js';
+import StatusProgressBar from './StatusProgressBar.js';
+/**
+ * The shared "labelled ellipses + optional determinate bar" body used by the
+ * loading/refetch indicators. Renders a {@link LoadingEllipses} label — with the
+ * rounded percent appended via {@link progressLabel} when `fraction` is
+ * determinate — and a determinate {@link StatusProgressBar} only when a
+ * `fraction` is present (an indeterminate phase shows just the animated label,
+ * no bar). Callers own the surrounding layout and supply `barClassName` for the
+ * bar width.
+ */
+export default function LoadingProgress({ message, fraction, variant, barClassName, }) {
+    return (_jsxs(_Fragment, { children: [_jsx(LoadingEllipses, { variant: variant, message: progressLabel(message || 'Loading', fraction) }), fraction === undefined ? null : (_jsx(StatusProgressBar, { className: barClassName, fraction: fraction }))] }));
+}

package/esm/ui/Logo.d.ts

@@ -2,6 +2,6 @@ type LogoVariant = 'color' | 'black' | 'white';
 interface LogoProps {
     variant?: LogoVariant;
 }
-export declare function Logomark({ variant }: LogoProps): import("react/jsx-runtime").JSX.Element;
-export declare function LogoFull({ variant }: LogoProps): import("react/jsx-runtime").JSX.Element;
+export declare function Logomark({ variant }: LogoProps): import("react").JSX.Element;
+export declare function LogoFull({ variant }: LogoProps): import("react").JSX.Element;
 export {};

package/esm/ui/Logo.js

@@ -1,30 +1,29 @@
-import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
-function getColors(variant) {
-    if (variant === 'black') {
-        return {
-            midnight: '#808080',
-            forrest: '#666666',
-            grape: '#4d4d4d',
-            mandarin: '#333333',
-            gray: '#1a1a1a',
-        };
-    }
-    if (variant === 'white') {
-        return {
-            midnight: '#ffffff',
-            forrest: '#e6e6e6',
-            grape: '#cccccc',
-            mandarin: '#b3b3b3',
-            gray: '#999999',
-        };
-    }
-    return {
+import { Fragment as _Fragment, jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+const colorSets = {
+    black: {
+        midnight: '#808080',
+        forest: '#666666',
+        grape: '#4d4d4d',
+        mandarin: '#333333',
+        gray: '#1a1a1a',
+    },
+    white: {
+        midnight: '#ffffff',
+        forest: '#e6e6e6',
+        grape: '#cccccc',
+        mandarin: '#b3b3b3',
+        gray: '#999999',
+    },
+    color: {
         midnight: '#0d233f',
-        forrest: '#135560',
+        forest: '#135560',
         grape: '#721e63',
         mandarin: '#ffb11d',
         gray: '#dadada',
-    };
+    },
+};
+function getColors(variant = 'color') {
+    return colorSets[variant];
 }
 export function Logomark({ variant }) {
     return (_jsx("svg", { viewBox: "0 0 175 175", children: _jsx(Icon, { variant: variant }) }));
@@ -34,7 +33,7 @@ export function LogoFull({ variant }) {
 }
 function Icon({ variant }) {
     const colors = getColors(variant);
-    return (_jsxs(_Fragment, { children: [_jsx("path", { style: { fill: colors.midnight }, d: "M120.5,57.5c.168,0,.333.012.5.013V40.506c-.167,0-.333-.006-.5-.006a98.325,98.325,0,0,0-77.4,37.565q-2.664,3.378-5.023,6.994l14.206,9.327Q54.043,91.709,56,89.179A81.363,81.363,0,0,1,120.5,57.5Z" }), _jsx("path", { style: { fill: colors.forrest }, d: "M148.668,86.223c.308.133.6.283.908.42l6.746-15.618c-.153-.067-.3-.143-.454-.21a81.36,81.36,0,0,0-71.777,3.5q-2.8,1.544-5.469,3.309l9.249,14.054A63.93,63.93,0,0,1,148.668,86.223Z" }), _jsx("path", { style: { fill: colors.grape }, d: "M170.894,109.37A63.929,63.929,0,0,0,113.4,88.861l2.336,15.474a48.456,48.456,0,0,1,44.322,15.42c.111.125.214.255.324.381l11.16-10C171.323,109.879,171.118,109.62,170.894,109.37Z" }), _jsx("path", { style: { fill: colors.mandarin }, d: "M150.921,150.314c.04.163.07.326.107.489l16.509-4.058c-.039-.163-.067-.326-.107-.489A48.457,48.457,0,0,0,135.575,111.8l-5.515,15.591A32.466,32.466,0,0,1,150.921,150.314Z" }), _jsx("path", { style: { fill: colors.gray }, d: "M134.1,138.129l-9.779,13.213a32.486,32.486,0,0,1,7.823,14.463l15.147.852c.012-.166.032-.331.041-.5A32.464,32.464,0,0,0,134.1,138.129Z" })] }));
+    return (_jsxs(_Fragment, { children: [_jsx("path", { style: { fill: colors.midnight }, d: "M120.5,57.5c.168,0,.333.012.5.013V40.506c-.167,0-.333-.006-.5-.006a98.325,98.325,0,0,0-77.4,37.565q-2.664,3.378-5.023,6.994l14.206,9.327Q54.043,91.709,56,89.179A81.363,81.363,0,0,1,120.5,57.5Z" }), _jsx("path", { style: { fill: colors.forest }, d: "M148.668,86.223c.308.133.6.283.908.42l6.746-15.618c-.153-.067-.3-.143-.454-.21a81.36,81.36,0,0,0-71.777,3.5q-2.8,1.544-5.469,3.309l9.249,14.054A63.93,63.93,0,0,1,148.668,86.223Z" }), _jsx("path", { style: { fill: colors.grape }, d: "M170.894,109.37A63.929,63.929,0,0,0,113.4,88.861l2.336,15.474a48.456,48.456,0,0,1,44.322,15.42c.111.125.214.255.324.381l11.16-10C171.323,109.879,171.118,109.62,170.894,109.37Z" }), _jsx("path", { style: { fill: colors.mandarin }, d: "M150.921,150.314c.04.163.07.326.107.489l16.509-4.058c-.039-.163-.067-.326-.107-.489A48.457,48.457,0,0,0,135.575,111.8l-5.515,15.591A32.466,32.466,0,0,1,150.921,150.314Z" }), _jsx("path", { style: { fill: colors.gray }, d: "M134.1,138.129l-9.779,13.213a32.486,32.486,0,0,1,7.823,14.463l15.147.852c.012-.166.032-.331.041-.5A32.464,32.464,0,0,0,134.1,138.129Z" })] }));
 }
 function Text({ variant }) {
     const colors = getColors(variant);

package/esm/ui/Menu.js

@@ -1 +1 @@
-export { default } from "./CascadingMenu.js";
+export { default } from './CascadingMenu.js';

package/esm/ui/MenuItemChevron.d.ts

@@ -0,0 +1,3 @@
+export declare function MenuItemChevron({ hidden }: {
+    hidden?: boolean;
+}): import("react").JSX.Element;

package/esm/ui/MenuItemChevron.js

@@ -0,0 +1,19 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import ChevronRight from '@mui/icons-material/ChevronRight';
+// The chevron a submenu row ends in, and — `hidden` — an invisible copy
+// reserving the identical footprint on a clickable row that has none, so a menu
+// carrying help on both kinds lands every "?" in one column.
+//
+// ONE COMPONENT, because "identical footprint" is the whole contract and two
+// bodies can drift: a `fontSize` added to one and not the other reintroduces
+// exactly the misalignment this exists to remove.
+//
+// A COPY, not a width. The column was a hard-coded 24, the px an MUI
+// `fontSize="medium"` icon is at MUI's own defaults. This theme sets
+// `typography.fontSize: 12`, which scales `pxToRem` by 12/14, so the chevron
+// actually draws at ~20.6px and every clickable row's "?" sat ~3.4px inboard of
+// the submenu rows'. Rendering the icon itself cannot be off by a scale factor
+// nothing here gets to see.
+export function MenuItemChevron({ hidden }) {
+    return _jsx(ChevronRight, { style: hidden ? { visibility: 'hidden' } : undefined });
+}

package/esm/ui/MenuItemEndDecoration.d.ts

@@ -0,0 +1,4 @@
+export declare function MenuItemEndDecoration({ type, checked, }: {
+    type: 'checkbox' | 'radio';
+    checked: boolean;
+}): import("react").JSX.Element;

package/esm/ui/MenuItemEndDecoration.js

@@ -0,0 +1,28 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import CheckBoxIcon from '@mui/icons-material/CheckBox';
+import CheckBoxOutlineBlankIcon from '@mui/icons-material/CheckBoxOutlineBlank';
+import RadioButtonCheckedIcon from '@mui/icons-material/RadioButtonChecked';
+import RadioButtonUncheckedIcon from '@mui/icons-material/RadioButtonUnchecked';
+import { makeStyles } from '../util/tss-react/index.js';
+const useStyles = makeStyles()({
+    menuItemEndDecoration: {
+        padding: 0,
+        margin: 0,
+        height: 16,
+    },
+});
+export function MenuItemEndDecoration({ type, checked, }) {
+    const { classes } = useStyles();
+    let icon;
+    switch (type) {
+        case 'checkbox': {
+            icon = checked ? (_jsx(CheckBoxIcon, {})) : (_jsx(CheckBoxOutlineBlankIcon, { color: "action" }));
+            break;
+        }
+        case 'radio': {
+            icon = checked ? (_jsx(RadioButtonCheckedIcon, {})) : (_jsx(RadioButtonUncheckedIcon, { color: "action" }));
+            break;
+        }
+    }
+    return _jsx("div", { className: classes.menuItemEndDecoration, children: icon });
+}

package/esm/ui/MenuItemTrailing.d.ts

@@ -0,0 +1,12 @@
+import type { ClickableMenuItem, SubMenuItem } from './MenuTypes.ts';
+export type DecoratedMenuItem = ClickableMenuItem | SubMenuItem;
+export interface MenuColumnFlags {
+    hasCheckboxOrRadioWithHelp: boolean;
+    hasEndAdornment: boolean;
+    hasSubmenuWithHelp: boolean;
+    sharedActionColumn: boolean;
+}
+export declare function MenuItemTrailing({ item, columns: { hasCheckboxOrRadioWithHelp, hasEndAdornment, hasSubmenuWithHelp, sharedActionColumn, }, }: {
+    item: DecoratedMenuItem;
+    columns: MenuColumnFlags;
+}): import("react").JSX.Element;

package/esm/ui/MenuItemTrailing.js

@@ -0,0 +1,42 @@
+import { Fragment as _Fragment, jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import CascadingMenuHelpIconButton, { CascadingMenuHelpIconSpacer, } from './CascadingMenuHelpIconButton.js';
+import { MenuItemChevron } from './MenuItemChevron.js';
+import { MenuItemEndDecoration } from './MenuItemEndDecoration.js';
+import { menuItemAdornment } from './menuItemAdornment.js';
+// gap that sets the value glyph (row state) apart from the trailing help/pin
+// action column, so a busy row reads as "value | actions" not one dense cluster
+const valueActionGap = 8;
+// fixed footprint reserved for the endAdornment column so pins right-align
+const endAdornmentColumnWidth = 28;
+// The checkbox/radio glyph reflecting a row's value. Held slightly apart from
+// the action column when the menu has one, so state and actions don't blur.
+function MenuItemValueGlyph({ type, checked, separated, }) {
+    return (_jsx("div", { style: { marginRight: separated ? valueActionGap : 0 }, children: _jsx(MenuItemEndDecoration, { type: type, checked: checked }) }));
+}
+// Fixed-width column holding an item's endAdornment (e.g. the "default for all"
+// pin). Reserved on every row of a menu that has any adornment so they
+// right-align into their own column.
+function MenuItemEndAdornmentSlot({ children }) {
+    return (_jsx("div", { style: {
+            width: endAdornmentColumnWidth,
+            display: 'flex',
+            justifyContent: 'flex-end',
+            alignItems: 'center',
+        }, children: children }));
+}
+// Everything trailing a menu row's label, for a clickable row and a submenu row
+// alike: a flex spacer that right-aligns the decorations, then the value glyph,
+// help affordance, endAdornment column, and the chevron column. When
+// `sharedActionColumn` is set, no row in the menu combines help with an
+// adornment, so the two share one trailing column (whichever this row has)
+// rather than each claiming its own.
+export function MenuItemTrailing({ item, columns: { hasCheckboxOrRadioWithHelp, hasEndAdornment, hasSubmenuWithHelp, sharedActionColumn, }, }) {
+    const isSubmenu = 'subMenu' in item;
+    const isCheckOrRadio = item.type === 'checkbox' || item.type === 'radio';
+    const hasActionColumn = hasCheckboxOrRadioWithHelp || hasEndAdornment;
+    // a disabled row can't open the help popover (pointer-events:none), so its
+    // helpText is surfaced as a hover tooltip by the row instead
+    const helpButton = item.helpText && !item.disabled ? (_jsx(CascadingMenuHelpIconButton, { helpText: item.helpText, label: item.label })) : undefined;
+    return (_jsxs(_Fragment, { children: [_jsx("div", { style: { flexGrow: 1, minWidth: 10 } }), isCheckOrRadio ? (_jsx(MenuItemValueGlyph, { type: item.type, checked: item.checked, separated: hasActionColumn })) : null, sharedActionColumn ? (_jsx(MenuItemEndAdornmentSlot, { children: helpButton ?? menuItemAdornment(item) })) : (_jsxs(_Fragment, { children: [helpButton ??
+                        (isCheckOrRadio && hasCheckboxOrRadioWithHelp ? (_jsx(CascadingMenuHelpIconSpacer, {})) : null), hasEndAdornment ? (_jsx(MenuItemEndAdornmentSlot, { children: menuItemAdornment(item) })) : null] })), isSubmenu ? (_jsx(MenuItemChevron, {})) : hasSubmenuWithHelp ? (_jsx(MenuItemChevron, { hidden: true })) : null] }));
+}

package/esm/ui/MenuTypes.d.ts

@@ -1,38 +1,128 @@
+/** #menuItem divider | a horizontal rule; not clickable */
 export interface MenuDivider {
     priority?: number;
     type: 'divider';
 }
+/** #menuItem subHeader | a text label for a section of a menu; not clickable */
 export interface MenuSubHeader {
     type: 'subHeader';
     priority?: number;
     label: string;
 }
+export type MenuItemClickHandler = (...args: any[]) => void;
 export interface BaseMenuItem {
+    /**
+     * #menuField stable identifier; keys the row, and finds it again from a test
+     *
+     * Worth setting on a row the menu cannot otherwise tell apart — one whose
+     * `label` is an element, or one a list may repeat the text of. A level's keys
+     * are unique either way (`rowKeys` suffixes a repeat), so this is what keeps a
+     * row's React identity when the rows around it reorder rather than something
+     * the menu needs to draw correctly.
+     */
     id?: string;
+    /** #menuField the row's text */
     label: React.ReactNode;
+    /** #menuField sort weight within the menu; higher sorts earlier */
     priority?: number;
+    /**
+     * #menuField secondary text under the label; prefer `withHint` in the label
+     *
+     * Renders as a second line under the label, which makes the row two lines
+     * tall. Nothing in this repo uses it any more: a menu whose rows are each two
+     * lines is harder to scan than the labels it buried, so a short clarifier
+     * goes in the label (`withHint` where it is conditional) and real prose goes
+     * in `helpText`. Kept because it renders and plugins may pass one.
+     */
     subLabel?: string;
+    /** #menuField any [MUI icon](https://mui.com/material-ui/material-icons/) component */
     icon?: React.ElementType;
+    /** #menuField renders the row unclickable */
     disabled?: boolean;
+    /** #menuField tooltip shown from a help icon at the trailing edge */
     helpText?: string;
+    /** #menuField tooltip shown when the item is disabled, in place of helpText */
+    disabledHelpText?: string;
+    /**
+     * #menuField override the dismiss-on-click rule; see `staysOpenOnClick`
+     *
+     * Override whether the menu stays open after this row is clicked. Leave it
+     * unset and the row TYPE decides: a `checkbox`/`radio` is a setting, so the
+     * menu stays put (users flip several in one visit, and the menu content is an
+     * observer, so its checked marks update live), while every other row is an
+     * action and dismisses.
+     *
+     * Set `false` on a checkbox/radio whose click is really terminal — it opens a
+     * dialog ("Custom...", "Solid color...") or swaps the display out from under
+     * the menu. Set `true` on a non-checkbox row that should survive its click.
+     */
+    keepMenuOpen?: boolean;
+    /**
+     * #menuField arbitrary trailing content
+     *
+     * Extra content rendered at the trailing (right) edge of the row, after the
+     * checkbox/radio decoration and help icon — e.g. a secondary toggle. The
+     * content must `stopPropagation` on its own click so it doesn't fire the row's
+     * onClick or dismiss the menu.
+     *
+     * An **element**, so a module that sets it drags React and whatever it renders
+     * into its own graph. Reach for it only when the content is genuinely
+     * arbitrary — synteny's and wiggle's colour swatches are what it exists for.
+     */
+    endAdornment?: React.ReactNode;
 }
+/** #menuItem normal | an action row; the default when `type` is omitted */
 export interface NormalMenuItem extends BaseMenuItem {
     type?: 'normal';
-    onClick: (...args: any[]) => void;
+    onClick: MenuItemClickHandler;
 }
+/** #menuItem checkbox | a setting row with a checkbox; leaves the menu open */
 export interface CheckboxMenuItem extends BaseMenuItem {
     type: 'checkbox';
     checked: boolean;
-    onClick: (...args: any[]) => void;
+    onClick: MenuItemClickHandler;
 }
+/** #menuItem radio | a setting row with a radio button; leaves the menu open */
 export interface RadioMenuItem extends BaseMenuItem {
     type: 'radio';
     checked: boolean;
-    onClick: (...args: any[]) => void;
+    onClick: MenuItemClickHandler;
 }
+/**
+ * #menuItem subMenu | nests another `MenuItem[]`, or a function building one, to any depth
+ *
+ * The function form is called when the submenu opens (or a walker asks for its
+ * rows), not when the parent menu is built — for a submenu whose rows cost a
+ * scan of the display's data to name. Read the field through `resolveSubMenu`
+ * rather than by hand, so the two forms stay one thing to the renderer and to
+ * every test helper that flattens a menu.
+ */
 export interface SubMenuItem extends BaseMenuItem {
     type?: 'subMenu';
-    subMenu: MenuItem[];
+    subMenu: MenuItem[] | (() => MenuItem[]);
 }
-export type MenuItem = MenuDivider | MenuSubHeader | NormalMenuItem | CheckboxMenuItem | RadioMenuItem | SubMenuItem;
+export declare function resolveSubMenu(item: SubMenuItem): MenuItem[];
+/**
+ * #menuItem custom | renders arbitrary React content inline, e.g. a slider
+ *
+ * The menu is not dismissed when interacting with it, so a control can be
+ * dragged live; `onClose` is passed for content that wants to close the menu
+ * explicitly. `label` is used only as a React key/testid.
+ */
+export interface CustomMenuItem extends BaseMenuItem {
+    type: 'custom';
+    render: (onClose: () => void) => React.ReactNode;
+}
+export type ClickableMenuItem = NormalMenuItem | CheckboxMenuItem | RadioMenuItem;
+export type MenuItem = MenuDivider | MenuSubHeader | NormalMenuItem | CheckboxMenuItem | RadioMenuItem | SubMenuItem | CustomMenuItem;
+/**
+ * Whether clicking a row leaves the menu up — the rule `CascadingMenu` applies,
+ * exported so a display's menu-shape test asserts the behavior a user gets
+ * rather than re-deriving it from the flag (each test that spelled out
+ * `keepMenuOpen === true` had to be revisited when the default moved here).
+ *
+ * Defaulted by row TYPE: a checkbox/radio is a setting and stays put, every
+ * other row is an action and dismisses. `keepMenuOpen` overrides either way.
+ */
+export declare function staysOpenOnClick(item: ClickableMenuItem): boolean;
 export type MenuItemsGetter = MenuItem[] | (() => MenuItem[]);

package/esm/ui/MenuTypes.js

@@ -1 +1,16 @@
-export {};
+export function resolveSubMenu(item) {
+    return typeof item.subMenu === 'function' ? item.subMenu() : item.subMenu;
+}
+// #endregion
+/**
+ * Whether clicking a row leaves the menu up — the rule `CascadingMenu` applies,
+ * exported so a display's menu-shape test asserts the behavior a user gets
+ * rather than re-deriving it from the flag (each test that spelled out
+ * `keepMenuOpen === true` had to be revisited when the default moved here).
+ *
+ * Defaulted by row TYPE: a checkbox/radio is a setting and stays put, every
+ * other row is an action and dismisses. `keepMenuOpen` overrides either way.
+ */
+export function staysOpenOnClick(item) {
+    return (item.keepMenuOpen ?? (item.type === 'checkbox' || item.type === 'radio'));
+}

package/esm/ui/MonospaceTextField.d.ts

@@ -0,0 +1,10 @@
+import type { TextFieldProps } from '@mui/material';
+export default function MonospaceTextField({ value, onChange, error, label, children, style, className, readOnly, inputTestId, helperText, variant, ...rest }: {
+    value: string;
+    onChange?: (value: string) => void;
+    error?: unknown;
+    label?: React.ReactNode;
+    children?: React.ReactNode;
+    readOnly?: boolean;
+    inputTestId?: string;
+} & Omit<TextFieldProps, 'value' | 'onChange' | 'error' | 'slotProps'>): import("react").JSX.Element;

package/esm/ui/MonospaceTextField.js

@@ -0,0 +1,40 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { InputLabel, TextField } from '@mui/material';
+import { makeStyles } from '../util/tss-react/index.js';
+import { alpha } from './palette.js';
+const monospaceFontFamily = 'Consolas, "Andale Mono WT", "Andale Mono", "Lucida Console", "Lucida Sans Typewriter", "DejaVu Sans Mono", "Bitstream Vera Sans Mono", "Liberation Mono", "Nimbus Mono L", Monaco, "Courier New", Courier, monospace';
+const useStyles = makeStyles()(theme => ({
+    container: {
+        width: '100%',
+        overflowX: 'auto',
+    },
+    field: {
+        fontFamily: monospaceFontFamily,
+    },
+    errorField: {
+        background: alpha(theme.palette.error.main, 0.15),
+    },
+}));
+// Monospace multiline TextField for code/jexl/JSON/sequence content. A parse
+// error turns it red and takes the helper text's place under the field, so
+// the text does not move while it flips between valid and invalid. `children`
+// render below the field (e.g. a description or help button).
+export default function MonospaceTextField({ value, onChange, error, label, children, style, className, readOnly, inputTestId, helperText, variant = 'outlined', ...rest }) {
+    const { classes, cx } = useStyles();
+    return (_jsxs("div", { className: classes.container, children: [label ? _jsx(InputLabel, { shrink: true, children: label }) : null, _jsx(TextField, { ...rest, variant: variant, multiline: true, error: !!error, helperText: error ? `${error}` : helperText, value: value, onChange: event => {
+                    onChange?.(event.target.value);
+                }, className: cx(className, error ? classes.errorField : undefined), style: style, slotProps: {
+                    input: {
+                        readOnly,
+                        classes: {
+                            input: classes.field,
+                        },
+                    },
+                    htmlInput: {
+                        'data-testid': inputTestId,
+                        spellCheck: false,
+                        autoCorrect: 'off',
+                        autoCapitalize: 'off',
+                    },
+                } }), children] }));
+}

package/esm/ui/NumberTextField.d.ts

@@ -0,0 +1,31 @@
+import type { TextFieldProps } from '@mui/material';
+interface OwnProps {
+    /** Initial numeric value; undefined renders as empty input. */
+    defaultValue?: number;
+    /**
+     * Fires on every keystroke with the parsed number, or undefined when
+     * the input is empty or invalid (NaN / out of bounds). The parent
+     * decides whether to gate submission on undefined.
+     */
+    onValueChange: (value: number | undefined) => void;
+    /** Optional inclusive lower bound. */
+    min?: number;
+    /** Optional inclusive upper bound. */
+    max?: number;
+    /** Shown under the input when the value is non-empty and invalid. */
+    errorText?: string;
+}
+type Props = Omit<TextFieldProps, 'value' | 'onChange' | 'type' | 'error'> & OwnProps & {
+    helperText?: TextFieldProps['helperText'];
+};
+/**
+ * Uncontrolled-style numeric TextField. Owns the input *text* internally;
+ * emits the parsed *number* (or undefined) to the parent on every change.
+ *
+ * Use over `<TextField type="number" />` — the browser number input has
+ * known UX problems (scroll-to-change, locale issues, browser-specific
+ * spinners). This component keeps a plain text input and validates with
+ * `Number.isFinite` + optional min/max.
+ */
+export default function NumberTextField(props: Props): import("react").JSX.Element;
+export {};

package/esm/ui/NumberTextField.js

@@ -0,0 +1,33 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { useState } from 'react';
+import { TextField } from '@mui/material';
+/**
+ * Uncontrolled-style numeric TextField. Owns the input *text* internally;
+ * emits the parsed *number* (or undefined) to the parent on every change.
+ *
+ * Use over `<TextField type="number" />` — the browser number input has
+ * known UX problems (scroll-to-change, locale issues, browser-specific
+ * spinners). This component keeps a plain text input and validates with
+ * `Number.isFinite` + optional min/max.
+ */
+export default function NumberTextField(props) {
+    const { defaultValue, onValueChange, min, max, errorText = 'Must be a valid number', helperText, ...rest } = props;
+    const [text, setText] = useState(defaultValue === undefined ? '' : `${defaultValue}`);
+    const parsed = parseInBounds(text, min, max);
+    const showError = text !== '' && parsed === undefined;
+    return (_jsx(TextField, { ...rest, value: text, error: showError, helperText: showError ? errorText : helperText, autoComplete: "off", onChange: event => {
+            const next = event.target.value;
+            setText(next);
+            onValueChange(parseInBounds(next, min, max));
+        } }));
+}
+function parseInBounds(text, min, max) {
+    if (text === '') {
+        return undefined;
+    }
+    const n = Number(text);
+    const ok = Number.isFinite(n) &&
+        (min === undefined || n >= min) &&
+        (max === undefined || n <= max);
+    return ok ? n : undefined;
+}

package/esm/ui/PaletteContext.d.ts

@@ -0,0 +1,90 @@
+import type { JBrowsePalette } from './palette.ts';
+import type { JBrowseStyleTheme } from './styleTheme.ts';
+import type { ReactNode } from 'react';
+/**
+ * Supply the whole style theme — colors plus spacing and type scale. This is
+ * what JBrowse's own products mount, from `session.styleTheme`, so a config
+ * `theme` that sets `spacing` or `typography` reaches `makeStyles` and Material
+ * UI alike.
+ */
+export declare function StyleThemeProvider({ theme, children, }: {
+    theme: JBrowseStyleTheme;
+    children: ReactNode;
+}): import("react").JSX.Element;
+/**
+ * Supply colors only, leaving JBrowse's default sizing in place. The narrower
+ * of the two, and what a host that already holds a palette mounts: it is saying
+ * what JBrowse should draw *with*, not restating its type scale.
+ *
+ * **A host following its own light/dark state wants
+ * {@link SessionPaletteProvider} instead**, which is this plus the session
+ * write that the worker-side half of the rendering derives from. This one
+ * colors React and nothing else.
+ */
+export declare function PaletteProvider({ palette, children, }: {
+    palette: JBrowsePalette;
+    children: ReactNode;
+}): import("react").JSX.Element;
+export declare function useStyleTheme(): JBrowseStyleTheme;
+export declare function usePalette(): JBrowsePalette;
+/** What {@link useSessionPalette} needs of a session. */
+export interface ThemeModeSession {
+    setThemeMode: (mode: 'light' | 'dark') => void;
+    readonly palette: JBrowsePalette;
+}
+/**
+ * Point a session at light or dark and get back the palette it resolves to,
+ * for a host that wants the palette itself — to read a color out of, or to
+ * hand somewhere other than a provider. A host that only wants JBrowse to
+ * follow its dark mode mounts {@link SessionPaletteProvider}, which is this
+ * hook and the provider in one.
+ *
+ * Pass no mode and JBrowse follows the page: its declared CSS `color-scheme`
+ * when that names one of light or dark, the OS preference otherwise, tracking
+ * both. A host whose mode lives somewhere a stylesheet cannot see passes it.
+ *
+ * **Both halves are load-bearing, which is why the pairing is published as a
+ * component.** The palette is what *React* draws with; the config `theme` slot
+ * this writes is also what ships to the RPC worker, where feature labels are
+ * baked into the rendered image. Mount `PaletteProvider` on a palette from
+ * somewhere else and those labels stay in the old mode — light text on a light
+ * image, and no error anywhere. `setThemeMode` writes the one slot both are
+ * derived from, which is why this returns the palette rather than taking one.
+ *
+ * The write lands in an effect, so the first paint after a mode change uses
+ * the previous palette. That is a frame on a canvas that is about to be
+ * redrawn anyway; it is not somewhere to add a suspense boundary.
+ */
+export declare function useSessionPalette(session: ThemeModeSession, mode?: 'light' | 'dark'): JBrowsePalette;
+/**
+ * #api
+ * Make JBrowse follow the host's light/dark state — the whole of it, in one
+ * mount:
+ *
+ * ```tsx
+ * <SessionPaletteProvider session={session} mode={myAppIsDark ? 'dark' : 'light'}>
+ *   {tracks}
+ * </SessionPaletteProvider>
+ * ```
+ *
+ * `mode` is optional. Left out, JBrowse follows the page's declared
+ * `color-scheme` — so a host whose dark-mode toggle sets it, as most do, mounts
+ * this with a session and nothing else — and the OS preference where the page
+ * declares none.
+ *
+ * A component rather than a documented pair of calls because the pair has a
+ * half that can be left out with nothing to show for it. `PaletteProvider` is
+ * the name a host reaches for, and it colors the React side alone; the session
+ * write is what reaches the RPC worker, which bakes feature labels into the
+ * rendered image. So a host that mounts only the provider gets light-mode
+ * labels on a dark page, from a canvas whose every other pixel is right, and
+ * nothing errors. See {@link useSessionPalette} for the mechanism.
+ *
+ * The session is the only thing that resolves a palette here, so a host
+ * supplying colors of its own mounts `PaletteProvider` directly instead.
+ */
+export declare function SessionPaletteProvider({ session, mode, children, }: {
+    session: ThemeModeSession;
+    mode?: 'light' | 'dark';
+    children: ReactNode;
+}): import("react").JSX.Element;