@jbrowse/core 5.0.0-beta.1 → 5.0.0-beta.11

package/esm/ui/JexlFilterRowEditors.js

@@ -0,0 +1,90 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import CloseIcon from '@mui/icons-material/Close';
+import { Autocomplete, IconButton, ListItemText, MenuItem, TextField, } from '@mui/material';
+import { OPERATORS, stripJexlPrefix, typedField, withField, withOp, } from '../util/jexlFilterRows.js';
+import { makeStyles } from '../util/tss-react/index.js';
+import MonospaceTextField from './MonospaceTextField.js';
+const useStyles = makeStyles()(theme => ({
+    row: {
+        display: 'flex',
+        alignItems: 'flex-start',
+        gap: theme.spacing(1),
+        marginBottom: theme.spacing(1),
+    },
+    field: {
+        width: 220,
+        flexShrink: 0,
+    },
+    op: {
+        width: 130,
+        flexShrink: 0,
+    },
+    value: {
+        flex: 1,
+    },
+    expression: {
+        width: 24,
+        flexShrink: 0,
+        textAlign: 'center',
+        fontStyle: 'italic',
+        fontFamily: 'serif',
+        fontSize: 18,
+        paddingTop: 6,
+        color: theme.palette.text.secondary,
+    },
+}));
+export function compileError(line, jexl) {
+    try {
+        jexl.compile(stripJexlPrefix(line.trim()));
+        return undefined;
+    }
+    catch (e) {
+        return e instanceof Error ? e.message : String(e);
+    }
+}
+function RemoveButton({ onClick }) {
+    return (_jsx(IconButton, { size: "small", "aria-label": "Remove condition", onClick: onClick, children: _jsx(CloseIcon, { fontSize: "small" }) }));
+}
+function ValueInput({ row, onChange, }) {
+    const { classes } = useStyles();
+    const { field, op, value } = row;
+    if (op === 'set' || op === '!set') {
+        return _jsx("div", { className: classes.value });
+    }
+    const suggestions = field?.values ?? [];
+    if (op === 'in') {
+        return (_jsx(Autocomplete, { className: classes.value, size: "small", multiple: true, freeSolo: true, autoSelect: true, options: suggestions, value: [value].flat(), onChange: (_, next) => {
+                onChange({ ...row, value: next });
+            }, renderInput: params => (_jsx(TextField, { ...params, placeholder: "Values, Enter after each" })) }));
+    }
+    const text = [value].flat()[0] ?? '';
+    return suggestions.length > 0 && op !== '~' ? (_jsx(Autocomplete, { className: classes.value, size: "small", freeSolo: true, options: suggestions, inputValue: text, onInputChange: (_, next) => {
+            onChange({ ...row, value: next });
+        }, renderInput: params => _jsx(TextField, { ...params, placeholder: "Value" }) })) : (_jsx(TextField, { className: classes.value, size: "small", placeholder: op === '~' ? 'Regular expression' : 'Value', type: field?.type === 'number' ? 'number' : 'text', disabled: !field, value: text, onChange: event => {
+            onChange({ ...row, value: event.target.value });
+        } }));
+}
+export function ConditionRowEditor({ row, choices, onChange, onRemove, }) {
+    const { classes } = useStyles();
+    const { field } = row;
+    const grouped = choices.some(choice => choice.group);
+    return (_jsxs("div", { className: classes.row, children: [_jsx(Autocomplete, { className: classes.field, size: "small", freeSolo: true, autoSelect: true, options: choices, groupBy: grouped ? choice => choice.group ?? '' : undefined, getOptionLabel: choice => typeof choice === 'string' ? choice : choice.label, getOptionKey: choice => typeof choice === 'string' ? choice : choice.key, isOptionEqualToValue: (a, b) => typeof b !== 'string' && a.key === b.key, value: field ?? null, onChange: (_, next) => {
+                    const chosen = typeof next !== 'string'
+                        ? next
+                        : next === field?.label
+                            ? field
+                            : (choices.find(choice => choice.label === next) ??
+                                typedField(next));
+                    if (chosen && chosen.key !== field?.key) {
+                        onChange(withField(row, chosen));
+                    }
+                }, renderOption: ({ key, ...props }, choice) => (_jsx("li", { ...props, children: _jsx(ListItemText, { primary: choice.label, secondary: choice.description }) }, key)), renderInput: params => _jsx(TextField, { ...params, placeholder: "Field" }) }), _jsx(TextField, { className: classes.op, select: true, size: "small", disabled: !field, value: row.op, helperText: field?.multi ? 'any value' : undefined, onChange: event => {
+                    onChange(withOp(row, event.target.value));
+                }, children: OPERATORS[field?.type ?? 'any'].map(({ op, label }) => (_jsx(MenuItem, { value: op, children: label }, op))) }), _jsx(ValueInput, { row: row, onChange: onChange }), _jsx(RemoveButton, { onClick: onRemove })] }));
+}
+export function TextRowEditor({ row, jexl, onChange, onRemove, }) {
+    const { classes } = useStyles();
+    return (_jsxs("div", { className: classes.row, children: [_jsx("div", { className: classes.expression, title: "An expression the field pickers cannot show", children: "\u0192" }), _jsx(MonospaceTextField, { className: classes.value, variant: "standard", fullWidth: true, value: row.text, error: compileError(row.text, jexl), onChange: text => {
+                    onChange({ ...row, text });
+                } }), _jsx(RemoveButton, { onClick: onRemove })] }));
+}

package/esm/ui/LazyBaseTooltip.d.ts

@@ -0,0 +1,4 @@
+import type { ComponentProps } from 'react';
+declare const Lazy: import("react").LazyExoticComponent<typeof import("./BaseTooltip.tsx").default>;
+export default function LazyBaseTooltip(props: ComponentProps<typeof Lazy>): import("react").JSX.Element;
+export {};

package/esm/ui/LazyBaseTooltip.js

@@ -0,0 +1,9 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { Suspense, lazy } from 'react';
+// The tooltip, behind its own chunk: @floating-ui is ~266KB and this is what
+// lets the ui barrel export it without putting that on the startup path. A
+// consumer that wants the eager component deep-imports './BaseTooltip.tsx'.
+const Lazy = lazy(() => import('./BaseTooltip.js'));
+export default function LazyBaseTooltip(props) {
+    return (_jsx(Suspense, { fallback: null, children: _jsx(Lazy, { ...props }) }));
+}

package/esm/ui/LegendSwatchGlyph.js

@@ -1,25 +1,30 @@
 import { jsx as _jsx } from "react/jsx-runtime";
-// The one place that decides what each `LegendMark` looks like. Returns bare SVG
-// shapes rather than a rooted <svg>, so the floating legend (which wraps them in
-// an inline <svg>) and the SVG export (which drops them into a row <g>) draw the
-// identical glyph — a display's on-screen key and its exported figure disagreeing
-// about which color is a curve would be worse than neither having marks.
+import { appendGlyph } from '@jbrowse/render-core/marks/glyphPaint';
+import { DIAMOND_GLYPH_SCALE } from '@jbrowse/render-core/shaders/pointMarkConsts';
+import { SHAPE_CODES } from '../util/shapeNames.js';
+// The point mark's own painter, recorded as SVG path data, so the key draws
+// the glyph the plot draws. The diamond paints wider than its diameter and
+// is scaled down to fit the box.
+function glyphPathData(shape, size, x, y) {
+    const d = [];
+    const path = {
+        moveTo: (px, py) => d.push(`M${px} ${py}`),
+        lineTo: (px, py) => d.push(`L${px} ${py}`),
+        closePath: () => d.push('Z'),
+        rect: (px, py, w, h) => d.push(`M${px} ${py}h${w}v${h}h${-w}Z`),
+        arc: (cx, cy, r) => d.push(`A${r} ${r} 0 1 0 ${cx - r} ${cy}A${r} ${r} 0 1 0 ${cx + r} ${cy}Z`),
+    };
+    const diameter = shape === 'diamond' ? size / DIAMOND_GLYPH_SCALE : size;
+    appendGlyph(path, SHAPE_CODES[shape], x + size / 2, y + size / 2, diameter);
+    return d.join('');
+}
+// The one place that decides what a legend swatch looks like. Returns a bare
+// shape rather than a rooted <svg>, so the floating legend (which wraps it in an
+// inline <svg>) and the SVG export (which drops it into a row <g>) draw the
+// identical box.
 //
-// Every shape fills the `size` box from (x, y) so a caller can lay swatches out
-// on a fixed pitch without knowing which mark it is placing.
+// The shape fills the `size` box from (x, y) so a caller can lay swatches out on
+// a fixed pitch.
 export function LegendSwatchGlyph({ swatch, size, x = 0, y = 0, }) {
-    const { color, mark = 'fill' } = swatch;
-    // Thin enough to read as a stroke next to a solid block, thick enough to
-    // carry a color at 10-12px.
-    const strokeWidth = Math.max(2, Math.round(size / 5));
-    if (mark === 'line') {
-        return (_jsx("line", { x1: x, x2: x + size, y1: y + size / 2, y2: y + size / 2, stroke: color, strokeWidth: strokeWidth }));
-    }
-    if (mark === 'curve') {
-        // An arc bulging up out of the box's lower corners, which is the shape of
-        // the connector itself — a pair of endpoints with the curve between them.
-        const inset = strokeWidth / 2;
-        return (_jsx("path", { d: `M${x},${y + size - inset} Q${x + size / 2},${y - size / 3} ${x + size},${y + size - inset}`, fill: "none", stroke: color, strokeWidth: strokeWidth }));
-    }
-    return _jsx("rect", { x: x, y: y, width: size, height: size, fill: color });
+    return swatch.shape ? (_jsx("path", { d: glyphPathData(swatch.shape, size, x, y), fill: swatch.color })) : (_jsx("rect", { x: x, y: y, width: size, height: size, fill: swatch.color }));
 }

package/esm/ui/LoadingOverlay.d.ts

@@ -1,3 +1,17 @@
+/**
+ * Returns false, then flips true once `active` has stayed true continuously for
+ * `delayMs`. Each activation gets a fresh delay, and the flag drops the moment
+ * `active` does.
+ *
+ * Keyed on a count of RISING edges rather than on `active` itself, so the
+ * falling edge does no work at all. A display refetching through a wheel zoom
+ * flips `active` several times a second — it finishes a fetch, waits out the
+ * debounce, starts the next — and an effect depending on `active` tore its timer
+ * down and built a new one on each of those, twice over, for a scrim that by
+ * construction never appears. Deriving the flag from a comparison instead means
+ * one `setTimeout` per loading pulse, which is the floor for these semantics.
+ */
+export declare function useDelayedFlag(active: boolean, delayMs: number): boolean;
 export default function LoadingOverlay({ statusMessage, progress, isVisible, immediate, canceled, onCancel, onRetry, }: {
     statusMessage?: string;
     progress?: number;

package/esm/ui/LoadingOverlay.js

@@ -27,7 +27,7 @@ const flashDelayMs = 250;
  * construction never appears. Deriving the flag from a comparison instead means
  * one `setTimeout` per loading pulse, which is the floor for these semantics.
  */
-function useDelayedFlag(active, delayMs) {
+export function useDelayedFlag(active, delayMs) {
     const [previous, setPrevious] = useState(active);
     const [activation, setActivation] = useState(0);
     if (previous !== active) {
@@ -129,7 +129,9 @@ export default function LoadingOverlay({ statusMessage, progress, isVisible, imm
     // swallow clicks/hovers over the top-center of every track it overlays. There
     // is no fade transition, so mount/unmount is visually identical to toggling
     // opacity anyway.
-    return shown ? (_jsx("span", { className: classes.overlay, "data-testid": "loading-overlay", children: _jsx("span", { className: classes.content, children: canceled ? (_jsxs("span", { className: classes.row, children: [_jsx("span", { className: classes.text, children: "Loading canceled" }), onRetry ? (_jsx(Tooltip, { title: "Retry", children: _jsx(IconButton, { size: "small", "data-testid": "loading-overlay-retry", onClick: () => {
+    // `loading-overlay` is a readiness selector meaning work in flight, so the
+    // canceled state, which is finished, publishes its own
+    return shown ? (_jsx("span", { className: classes.overlay, "data-testid": canceled ? 'loading-overlay-canceled' : 'loading-overlay', children: _jsx("span", { className: classes.content, children: canceled ? (_jsxs("span", { className: classes.row, children: [_jsx("span", { className: classes.text, children: "Loading canceled" }), onRetry ? (_jsx(Tooltip, { title: "Retry", children: _jsx(IconButton, { size: "small", "data-testid": "loading-overlay-retry", onClick: () => {
                                 onRetry();
                             }, children: _jsx(RefreshIcon, { fontSize: "inherit" }) }) })) : null] })) : (_jsxs(_Fragment, { children: [_jsxs("span", { className: classes.row, children: [_jsxs("span", { className: classes.text, children: [progressLabel(statusMessage || 'Loading', progress), hasProgress ? null : _jsx(LoadingDots, {})] }), onCancel && cancelable ? (_jsx(Tooltip, { title: "Cancel", children: _jsx(IconButton, { size: "small", "data-testid": "loading-overlay-cancel", onClick: () => {
                                         onCancel();

package/esm/ui/MenuTypes.d.ts

@@ -1,4 +1,3 @@
-import type { Pin } from '../configuration/promotablePin.ts';
 /** #menuItem divider | a horizontal rule; not clickable */
 export interface MenuDivider {
     priority?: number;
@@ -12,7 +11,15 @@ export interface MenuSubHeader {
 }
 export type MenuItemClickHandler = (...args: any[]) => void;
 export interface BaseMenuItem {
-    /** #menuField stable identifier, for tests and for finding a row again */
+    /**
+     * #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;
@@ -51,7 +58,7 @@ export interface BaseMenuItem {
      */
     keepMenuOpen?: boolean;
     /**
-     * #menuField arbitrary trailing content; prefer `pin`
+     * #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
@@ -59,56 +66,10 @@ export interface BaseMenuItem {
      * onClick or dismiss the menu.
      *
      * An **element**, so a module that sets it drags React and whatever it renders
-     * into its own graph. That is fine for the one-off it exists for (synteny's
-     * color swatch) and wrong for the common case, which is why the pin below is
-     * a description instead. Prefer `pin`; reach for this only when the
-     * content is genuinely arbitrary.
+     * 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;
-    /**
-     * #menuField the "apply this to all open tracks of this type" pin; set it with a promotable builder
-     *
-     * The trailing "default for all tracks of this type" pin, as a **description**
-     * rather than an element — the renderer builds `PinAdornment` from
-     * it. Same rule as a `TrackControlProps` icon name (reference/DISPLAYCHROME.md):
-     * menu-item builders are called from state models and menu modules, which are
-     * eager, so an element here puts MUI's `ToggleButton`, `Tooltip` and two icons
-     * into every host's first paint. It did, until 2026-08-05; see
-     * reference/EAGER_BUNDLE.md.
-     *
-     * Set it through `promotableToggleItem` / `promotableRadioItems` (or
-     * `promotableRadioItem` for a lone row), not by hand.
-     *
-     * A `type: 'custom'` row (`makePromotableSizeMenu`) draws its own pin inside
-     * its rendered content and still sets this — the declaration is what lets a
-     * built menu be asked which promotable slots it offers a pin for at all. Such
-     * a row is excluded from the trailing-column reservation; see
-     * `hasMenuItemAdornment`.
-     */
-    pin?: MenuItemPin;
-}
-/**
- * A row's pin declaration: the {@link Pin} `makePin` built, plus the one thing
- * the row knows and the pin doesn't — what to call the setting.
- *
- * **`control` holds the pin by reference; don't flatten this into
- * `interface MenuItemPin extends Pin`.** That was tried, to save the hop every
- * reader spells (`item.pin.control.active`), and it turns the declaration into a
- * *copy* of the control — so a `Pin` whose `toggle` resolves anything through
- * `this` silently mutates the copy and the real control never changes. Nothing in
- * `Pin` promises copy-safety: `makePin` happens to close over what it needs, but
- * the interface is a plain object a plugin can build by hand, and the failure is
- * a pin that draws correctly and does nothing. Two hops in `pinnedSlots` and
- * `menuItemAdornment` is the whole cost of not having that.
- */
-export interface MenuItemPin {
-    control: Pin;
-    /**
-     * Names the setting in the pin's tooltip and aria-label. Carried here rather
-     * than read off the row's `label`, which is a `ReactNode` and may not be a
-     * string; a pin that can't name what it promotes reads as a bug.
-     */
-    label: string;
 }
 /** #menuItem normal | an action row; the default when `type` is omitted */
 export interface NormalMenuItem extends BaseMenuItem {
@@ -127,11 +88,20 @@ export interface RadioMenuItem extends BaseMenuItem {
     checked: boolean;
     onClick: MenuItemClickHandler;
 }
-/** #menuItem subMenu | nests another `MenuItem[]`, to any depth */
+/**
+ * #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 declare function resolveSubMenu(item: SubMenuItem): MenuItem[];
 /**
  * #menuItem custom | renders arbitrary React content inline, e.g. a slider
  *

package/esm/ui/MenuTypes.js

@@ -1,3 +1,6 @@
+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,

package/esm/ui/MonospaceTextField.d.ts

@@ -1,9 +1,10 @@
 import type { TextFieldProps } from '@mui/material';
-export default function MonospaceTextField({ value, onChange, error, label, children, style, className, readOnly, variant, ...rest }: {
+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

@@ -1,12 +1,9 @@
-import { Fragment as _Fragment, jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
-import { InputLabel, TextField, alpha } from '@mui/material';
+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 => ({
-    error: {
-        color: theme.palette.error.main,
-        fontSize: '0.8em',
-    },
     container: {
         width: '100%',
         overflowX: 'auto',
@@ -18,20 +15,26 @@ const useStyles = makeStyles()(theme => ({
         background: alpha(theme.palette.error.main, 0.15),
     },
 }));
-// Monospace multiline TextField for code/jexl/JSON/sequence content. Turns red
-// on a parse error, renders an optional error banner above and an InputLabel,
-// and applies the shared monospace font stack to the input slot. `children`
+// 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, variant = 'outlined', ...rest }) {
+export default function MonospaceTextField({ value, onChange, error, label, children, style, className, readOnly, inputTestId, helperText, variant = 'outlined', ...rest }) {
     const { classes, cx } = useStyles();
-    return (_jsxs(_Fragment, { children: [error ? _jsx("p", { className: classes.error, children: `${error}` }) : null, _jsxs("div", { className: classes.container, children: [label ? _jsx(InputLabel, { shrink: true, children: label }) : null, _jsx(TextField, { ...rest, variant: variant, multiline: true, value: value, onChange: event => {
-                            onChange?.(event.target.value);
-                        }, className: cx(className, error ? classes.errorField : undefined), style: style, slotProps: {
-                            input: {
-                                readOnly,
-                                classes: {
-                                    input: classes.field,
-                                },
-                            },
-                        } }), children] })] }));
+    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/PaletteContext.d.ts

@@ -39,9 +39,9 @@ export interface ThemeModeSession {
  * follow its dark mode mounts {@link SessionPaletteProvider}, which is this
  * hook and the provider in one.
  *
- * How the host knows its own mode is the host's business — an attribute on
- * `<html>`, a `prefers-color-scheme` media query, a design-system context —
- * and deliberately not this hook's.
+ * 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
@@ -55,7 +55,7 @@ export interface ThemeModeSession {
  * 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;
+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
@@ -67,6 +67,11 @@ export declare function useSessionPalette(session: ThemeModeSession, mode: 'ligh
  * </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
@@ -80,6 +85,6 @@ export declare function useSessionPalette(session: ThemeModeSession, mode: 'ligh
  */
 export declare function SessionPaletteProvider({ session, mode, children, }: {
     session: ThemeModeSession;
-    mode: 'light' | 'dark';
+    mode?: 'light' | 'dark';
     children: ReactNode;
 }): import("react").JSX.Element;

package/esm/ui/PaletteContext.js

@@ -1,5 +1,6 @@
 import { jsx as _jsx } from "react/jsx-runtime";
-import { createContext, use, useEffect, useMemo } from 'react';
+import { createContext, use, useEffect, useMemo, useSyncExternalStore, } from 'react';
+import { onColorSchemeChange, prefersDarkColorScheme, } from '../util/systemColorScheme.js';
 import { defaultStyleTheme } from './styleTheme.js';
 /**
  * How a React component asks for JBrowse's design tokens.
@@ -47,6 +48,37 @@ export function useStyleTheme() {
 export function usePalette() {
     return useStyleTheme().palette;
 }
+function subscribeToColorScheme(onChange) {
+    const unsubscribe = onColorSchemeChange(onChange);
+    const observer = typeof MutationObserver === 'function'
+        ? new MutationObserver(onChange)
+        : undefined;
+    observer?.observe(document.documentElement, { attributes: true });
+    return () => {
+        unsubscribe();
+        observer?.disconnect();
+    };
+}
+// The page's declared `color-scheme`, as the browser resolves it for form
+// controls: a page that declares only one of light or dark gets that one, and
+// one that declares both, or neither, gets the OS preference.
+function readColorScheme() {
+    const declared = getComputedStyle(document.documentElement)
+        .getPropertyValue('color-scheme')
+        .split(/\s+/)
+        .filter((word) => ['light', 'dark'].includes(word));
+    return declared.length === 1
+        ? declared[0]
+        : prefersDarkColorScheme()
+            ? 'dark'
+            : 'light';
+}
+const alwaysLight = () => 'light';
+const subscribeToNothing = () => () => { };
+function useResolvedMode(mode) {
+    const systemMode = useSyncExternalStore(mode === undefined ? subscribeToColorScheme : subscribeToNothing, mode === undefined ? readColorScheme : alwaysLight, alwaysLight);
+    return mode === undefined ? systemMode : mode;
+}
 /**
  * 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
@@ -54,9 +86,9 @@ export function usePalette() {
  * follow its dark mode mounts {@link SessionPaletteProvider}, which is this
  * hook and the provider in one.
  *
- * How the host knows its own mode is the host's business — an attribute on
- * `<html>`, a `prefers-color-scheme` media query, a design-system context —
- * and deliberately not this hook's.
+ * 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
@@ -71,9 +103,10 @@ export function usePalette() {
  * redrawn anyway; it is not somewhere to add a suspense boundary.
  */
 export function useSessionPalette(session, mode) {
+    const resolved = useResolvedMode(mode);
     useEffect(() => {
-        session.setThemeMode(mode);
-    }, [session, mode]);
+        session.setThemeMode(resolved);
+    }, [session, resolved]);
     return session.palette;
 }
 /**
@@ -87,6 +120,11 @@ export function useSessionPalette(session, mode) {
  * </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

package/esm/ui/RefNameAutocomplete/SearchOption.d.ts

@@ -0,0 +1,13 @@
+import type { Assembly } from '../../assemblyManager/assembly.ts';
+import type { TrackCatalog } from '../../util/index.ts';
+import type { Option } from './util.ts';
+import type { HTMLAttributes, Key } from 'react';
+declare const SearchOption: ({ props, option, session, assembly, }: {
+    props: HTMLAttributes<HTMLLIElement> & {
+        key: Key;
+    };
+    option: Option;
+    session: TrackCatalog;
+    assembly?: Assembly;
+}) => import("react").JSX.Element;
+export default SearchOption;

package/esm/ui/RefNameAutocomplete/SearchOption.js

@@ -0,0 +1,45 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { observer } from 'mobx-react';
+import { groupByPlace } from '../../TextSearch/places.js';
+import { getTrackName } from '../../util/tracks.js';
+import { makeStyles } from '../../util/tss-react/index.js';
+import { optionDetail } from './util.js';
+const useStyles = makeStyles()(theme => ({
+    row: {
+        display: 'flex',
+        alignItems: 'baseline',
+        gap: theme.spacing(2),
+    },
+    label: {
+        flexShrink: 0,
+        whiteSpace: 'nowrap',
+    },
+    detail: {
+        marginLeft: 'auto',
+        minWidth: 0,
+        overflow: 'hidden',
+        textOverflow: 'ellipsis',
+        whiteSpace: 'nowrap',
+        fontSize: '0.8em',
+        color: theme.palette.text.secondary,
+    },
+}));
+const SearchOption = observer(function SearchOption({ props, option, session, assembly, }) {
+    const { classes, cx } = useStyles();
+    const { key, className, ...rest } = props;
+    const { result } = option;
+    const detail = optionDetail(result, {
+        trackNameOf: trackId => {
+            const conf = session.getTrackById(trackId);
+            return conf ? getTrackName(conf, session) : undefined;
+        },
+        lengthOf: refName => {
+            const index = assembly?.refNameToIndex?.get(refName);
+            const region = index === undefined ? undefined : assembly?.regions?.[index];
+            return region ? region.end - region.start : undefined;
+        },
+        placesOf: results => groupByPlace(results, assembly),
+    });
+    return (_jsxs("li", { className: cx(className, classes.row), ...rest, children: [_jsx("span", { className: classes.label, children: result.getDisplayString() }), detail ? _jsx("span", { className: classes.detail, children: detail }) : null] }, key));
+});
+export default SearchOption;

package/esm/ui/RefNameAutocomplete/index.d.ts

@@ -1,12 +1,11 @@
 import type BaseResult from '../../TextSearch/BaseResults.ts';
 import type { AbstractSessionModel } from '../../util/index.ts';
-import type { StopToken } from '../../util/stopToken.ts';
 import type { CSSProperties, ReactNode } from 'react';
 declare const RefNameAutocomplete: ({ session, assemblyName, value, fetchResults, onSelect, onChange, minWidth, maxWidth, adornmentWidth, style, endAdornment, helperText, inputStyle, }: {
     session: AbstractSessionModel;
     assemblyName?: string;
     value?: string;
-    fetchResults: (query: string, stopToken?: StopToken) => Promise<BaseResult[]>;
+    fetchResults: (query: string, signal?: AbortSignal) => Promise<BaseResult[]>;
     onSelect?: (region: BaseResult) => void;
     onChange?: (val: string) => void;
     minWidth?: number;

package/esm/ui/RefNameAutocomplete/index.js

@@ -4,6 +4,7 @@ import { Autocomplete, TextField } from '@mui/material';
 import { observer } from 'mobx-react';
 import { useDebounce } from '../../util/hooks.js';
 import { useFetch } from '../../util/useFetch.js';
+import SearchOption from './SearchOption.js';
 import { cap, coerceToResult, getDeduplicatedResult, getInputWidth, getOptionLabel, getRefNameOptions, } from './util.js';
 const RefNameAutocomplete = observer(function RefNameAutocomplete({ session, assemblyName, value, fetchResults, onSelect, onChange, minWidth = 200, maxWidth = 550, adornmentWidth, style, endAdornment, helperText, inputStyle, }) {
     const { assemblyManager } = session;
@@ -24,7 +25,7 @@ const RefNameAutocomplete = observer(function RefNameAutocomplete({ session, ass
     // the named parameters below cannot be destructured out of
     shouldSearch
         ? ['refNameSearch', assemblyName, debouncedSearch]
-        : null, async (_tag, _assembly, query, stopToken) => getDeduplicatedResult(await fetchResults(query, stopToken)), {
+        : null, async (_tag, _assembly, query, signal) => getDeduplicatedResult(await fetchResults(query, signal)), {
         onError: e => {
             session.notifyError(`${e}`, e);
         },
@@ -71,7 +72,12 @@ const RefNameAutocomplete = observer(function RefNameAutocomplete({ session, ass
                     style: inputStyle,
                     ...(endAdornment !== undefined && { endAdornment }),
                 },
-            }, placeholder: "Search for location" })), getOptionLabel: getOptionLabel }));
+            }, placeholder: "Search for location" })), getOptionLabel: getOptionLabel, slotProps: {
+            popper: {
+                placement: 'bottom-start',
+                style: { width: 'max-content', minWidth: width, maxWidth: 480 },
+            },
+        }, renderOption: (props, option) => (_jsx(SearchOption, { props: props, option: option, session: session, assembly: assembly }, props.key)) }));
 });
 export default RefNameAutocomplete;
 export { default as RefNameAutocompleteEndAdornment } from './EndAdornment.js';