@jbrowse/core 4.3.0 → 5.0.0-beta.1

package/esm/ui/PluggableElements.d.ts

@@ -0,0 +1,23 @@
+import type PluginManager from '../PluginManager.ts';
+import type { ExtensionPointProps } from '../PluginManager.ts';
+import type { ElementExtensionPointName } from './addExtensionElement.tsx';
+/**
+ * Render every element contributed to an accumulating point — the overlay
+ * points, whose entries are `ReactNode`s put there by `addExtensionElement`.
+ *
+ * The list sibling of {@link PluggableComponent}, which renders the single
+ * component a `single` point resolves to. Which one a point takes is decided by
+ * its registry entry, not by the call site: `ElementExtensionPointName` accepts
+ * only the points whose `args` are `ReactNode[]`, so asking for a slot point
+ * here is a compile error rather than a component that renders nothing.
+ *
+ * observer for the same reason PluggableComponent is one: a contributor may
+ * scope itself on an observable, and the fold runs here rather than in the
+ * producer, so the read has to be tracked by this component's own reaction.
+ */
+declare const PluggableElements: <N extends ElementExtensionPointName>({ pluginManager, name, props, }: {
+    pluginManager: PluginManager;
+    name: N;
+    props: ExtensionPointProps<N>;
+}) => import("react").JSX.Element;
+export default PluggableElements;

package/esm/ui/PluggableElements.js

@@ -0,0 +1,24 @@
+import { Fragment as _Fragment, jsx as _jsx } from "react/jsx-runtime";
+import { observer } from 'mobx-react';
+/**
+ * Render every element contributed to an accumulating point — the overlay
+ * points, whose entries are `ReactNode`s put there by `addExtensionElement`.
+ *
+ * The list sibling of {@link PluggableComponent}, which renders the single
+ * component a `single` point resolves to. Which one a point takes is decided by
+ * its registry entry, not by the call site: `ElementExtensionPointName` accepts
+ * only the points whose `args` are `ReactNode[]`, so asking for a slot point
+ * here is a compile error rather than a component that renders nothing.
+ *
+ * observer for the same reason PluggableComponent is one: a contributor may
+ * scope itself on an observable, and the fold runs here rather than in the
+ * producer, so the read has to be tracked by this component's own reaction.
+ */
+const PluggableElements = observer(function PluggableElements({ pluginManager, name, props, }) {
+    // the empty accumulator is the point's own array type, and `props` satisfies
+    // its declared props by the signature above. TS can't narrow either through
+    // the generic key, so both are restated here — same as PluggableComponent
+    const elements = pluginManager.evaluateExtensionPoint(name, [], ...[props]);
+    return _jsx(_Fragment, { children: elements });
+});
+export default PluggableElements;

package/esm/ui/PluginStoreCard.d.ts

@@ -0,0 +1,17 @@
+import type { PluginDefinition } from '../pluginDefinitions.ts';
+import type { ResolvedPlugin } from '../util/pluginStore.ts';
+import type { JBrowsePlugin } from '../util/types/index.ts';
+/**
+ * One plugin-store entry. Presentational, and shared by every surface that
+ * installs from the store (the in-session plugin store widget, Desktop's global
+ * plugins dialog) so all of them install the version `resolvePlugin` picked —
+ * version-pinned, integrity-carrying, and refused when no published version
+ * supports this JBrowse.
+ */
+export default function PluginStoreCard({ plugin, resolved, installed, disabled, onInstall, }: {
+    plugin: JBrowsePlugin;
+    resolved: ResolvedPlugin;
+    installed: boolean;
+    disabled?: boolean;
+    onInstall: (definition: PluginDefinition) => void;
+}): import("react").JSX.Element;

package/esm/ui/PluginStoreCard.js

@@ -0,0 +1,45 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import AddIcon from '@mui/icons-material/Add';
+import CheckIcon from '@mui/icons-material/Check';
+import PersonIcon from '@mui/icons-material/Person';
+import { Button, Card, CardActions, CardContent, Chip, Typography, } from '@mui/material';
+import { makeStyles } from '../util/tss-react/index.js';
+import ExternalLink from './ExternalLink.js';
+const useStyles = makeStyles()({
+    card: {
+        margin: '0.5em',
+    },
+    bold: {
+        fontWeight: 600,
+    },
+    dataField: {
+        display: 'flex',
+        alignItems: 'center',
+    },
+    mr: {
+        marginRight: '0.5em',
+    },
+    tagRow: {
+        display: 'flex',
+        flexWrap: 'wrap',
+        gap: '0.3em',
+        marginTop: '0.5em',
+    },
+});
+/**
+ * One plugin-store entry. Presentational, and shared by every surface that
+ * installs from the store (the in-session plugin store widget, Desktop's global
+ * plugins dialog) so all of them install the version `resolvePlugin` picked —
+ * version-pinned, integrity-carrying, and refused when no published version
+ * supports this JBrowse.
+ */
+export default function PluginStoreCard({ plugin, resolved, installed, disabled, onInstall, }) {
+    const { classes } = useStyles();
+    const { definition, compatible, supportedRanges, pluginVersion } = resolved;
+    const installable = compatible && definition !== undefined;
+    return (_jsxs(Card, { variant: "outlined", className: classes.card, children: [_jsxs(CardContent, { children: [_jsx(Typography, { variant: "h5", children: _jsxs(ExternalLink, { href: `${plugin.location}#readme`, children: [plugin.name, pluginVersion ? ` (v${pluginVersion})` : ''] }) }), _jsxs("div", { className: classes.dataField, children: [_jsx(PersonIcon, { className: classes.mr }), _jsx(Typography, { children: plugin.authors.join(', ') })] }), _jsx(Typography, { className: classes.bold, children: "Description:" }), _jsx(Typography, { children: plugin.description }), plugin.tags?.length ? (_jsx("div", { className: classes.tagRow, children: plugin.tags.map(tag => (_jsx(Chip, { label: tag, size: "small", variant: "outlined" }, tag))) })) : null, compatible ? null : (_jsxs(Typography, { color: "error", children: ["Not compatible with this version of JBrowse (requires JBrowse", ' ', supportedRanges.join(' or '), ")"] }))] }), _jsx(CardActions, { children: _jsx(Button, { variant: "contained", disabled: installed || disabled || !installable, startIcon: installed ? _jsx(CheckIcon, {}) : _jsx(AddIcon, {}), onClick: () => {
+                        if (definition !== undefined) {
+                            onInstall(definition);
+                        }
+                    }, children: installed ? 'Installed' : 'Install' }) })] }));
+}

package/esm/ui/PopoverPicker.d.ts

@@ -0,0 +1,6 @@
+export default function PopoverPicker({ color, onChange, presetAlpha, unset, }: {
+    color: string;
+    onChange: (color: string) => void;
+    presetAlpha?: number;
+    unset?: boolean;
+}): import("react").JSX.Element;

package/esm/ui/PopoverPicker.js

@@ -0,0 +1,25 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { useState } from 'react';
+import { makeStyles } from '../util/tss-react/index.js';
+import { ColorPopover } from './ColorPicker.js';
+import { swatchStyle } from './colorSwatchStyle.js';
+const useStyles = makeStyles()({
+    picker: { position: 'relative' },
+    swatch: swatchStyle,
+    // Signals a color that isn't explicitly set — the swatch shows the effective
+    // (auto) color, dashed to distinguish it from a user-chosen value.
+    unset: {
+        border: '2px dashed #999',
+        boxSizing: 'border-box',
+    },
+});
+export default function PopoverPicker({ color, onChange, presetAlpha, unset, }) {
+    const [anchorEl, setAnchorEl] = useState(null);
+    const { classes, cx } = useStyles();
+    const isAuto = color === 'auto';
+    return (_jsxs("div", { className: classes.picker, children: [_jsx("div", { className: cx(classes.swatch, unset ? classes.unset : undefined), style: { backgroundColor: isAuto ? 'transparent' : color }, title: unset ? 'Automatic — click to set a custom color' : undefined, onClick: event => {
+                    setAnchorEl(event.currentTarget);
+                } }), _jsx(ColorPopover, { anchorEl: anchorEl, onClose: () => {
+                    setAnchorEl(null);
+                }, color: isAuto ? 'blue' : color, onChange: onChange, presetAlpha: presetAlpha })] }));
+}

package/esm/ui/PrerenderedCanvas.d.ts

@@ -6,5 +6,5 @@ declare function PrerenderedCanvas(props: {
     imageData?: unknown;
     showSoftClip?: boolean;
     blockKey?: string;
-}): import("react/jsx-runtime").JSX.Element;
+}): import("react").JSX.Element;
 export default PrerenderedCanvas;

package/esm/ui/PrerenderedCanvas.js

@@ -1,15 +1,15 @@
 import { jsx as _jsx } from "react/jsx-runtime";
 import { useEffect, useRef, useState } from 'react';
-import { drawImageOntoCanvasContext } from "../util/offscreenCanvasPonyfill.js";
+import { drawImageOntoCanvasContext } from '../util/offscreenCanvasPonyfill.js';
 function PrerenderedCanvas(props) {
     const { width, height, highResolutionScaling = 1, style = {}, imageData, blockKey, showSoftClip, } = props;
     const [done, setDone] = useState(false);
-    const featureCanvas = useRef(null);
+    const featureCanvasRef = useRef(null);
     useEffect(() => {
         if (!imageData) {
             return;
         }
-        const canvas = featureCanvas.current;
+        const canvas = featureCanvasRef.current;
         if (!canvas) {
             return;
         }
@@ -19,6 +19,7 @@ function PrerenderedCanvas(props) {
         }
         context.clearRect(0, 0, canvas.width, canvas.height);
         drawImageOntoCanvasContext(imageData, context);
+        // eslint-disable-next-line @eslint-react/set-state-in-effect
         setDone(true);
     }, [imageData]);
     return (_jsx("canvas", { "data-testid": [
@@ -28,6 +29,6 @@ function PrerenderedCanvas(props) {
             done ? 'done' : '',
         ]
             .filter(f => !!f)
-            .join('_'), ref: featureCanvas, width: width * highResolutionScaling, height: height * highResolutionScaling, style: { width, height, ...style } }));
+            .join('_'), ref: featureCanvasRef, width: width * highResolutionScaling, height: height * highResolutionScaling, style: { width, height, ...style } }));
 }
 export default PrerenderedCanvas;

package/esm/ui/ProgressChip.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Bottom-right progress chip for work running while usable content is already on
+ * screen: a refetch over stale geometry (dotplot, linear synteny), or a
+ * background job that is not a fetch at all (clustering, via `DisplayChrome`).
+ * It stays small and out of the way instead of masking the canvas the way the
+ * full loading overlay would, and surfaces the statusCallback message plus a
+ * determinate bar when the phase reports progress.
+ *
+ * Pure presentation — the caller owns the gate (its own `refetching` getter, or
+ * the chrome's "a status is set while the phase is ready") and the containing
+ * element owns the positioning context.
+ *
+ * It also owns the corner, unless `anchored={false}` says something else does.
+ * That escape exists because on the LGV side the corner is shared: the chrome
+ * anchors one box for both this and the display's control row, and a chip that
+ * pins itself lands *under* that row rather than above it.
+ */
+declare const ProgressChip: ({ status, anchored, }: {
+    /**
+     * What to show. One object rather than a message and a fraction side by side,
+     * so a `createStatusChannel` holder passes `status={model.fetchStatus}` and
+     * nothing has to restate the pair — the field names are the channel's, and
+     * {@link LoadingProgress}'s.
+     */
+    status: {
+        message?: string;
+        fraction?: number;
+    };
+    /**
+     * Pin to the bottom-right of the containing block (the default, and what a
+     * caller dropping this into its own positioned box wants). Pass `false` where
+     * something else already owns that corner and lays this out — `DisplayChrome`
+     * shares it with the display's control row.
+     */
+    anchored?: boolean;
+}) => import("react").JSX.Element;
+export default ProgressChip;

package/esm/ui/ProgressChip.js

@@ -0,0 +1,66 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { observer } from 'mobx-react';
+import { keyframes, makeStyles } from '../util/tss-react/index.js';
+import LoadingProgress from './LoadingProgress.js';
+// anti-flash: hold the chip hidden for the first moments so a fast job (which
+// unmounts the chip before the delay elapses) never flashes. The chip remounts
+// per job, so the delay restarts each time. 0s duration = no fade, it just
+// appears after the delay.
+const appear = keyframes `
+  from { opacity: 0; }
+  to { opacity: 0.8; }
+`;
+const useStyles = makeStyles()(theme => ({
+    root: {
+        // Kept out of `anchored` below, because it has to hold in both modes and
+        // does: a flex item honours `z-index` with no `position` of its own
+        // (Flexbox §5.4). In the chrome's shared corner this is what keeps the chip
+        // under the tree sidebar and the legends at 100, where it has always been.
+        zIndex: 2,
+        pointerEvents: 'none',
+        padding: '0 4px',
+        borderRadius: 4,
+        background: theme.palette.background.paper,
+        opacity: 0.8,
+        animation: `${appear} 0s linear 0.25s both`,
+        display: 'flex',
+        flexDirection: 'column',
+        alignItems: 'center',
+    },
+    // Separated from the presentation above because the two callers differ on who
+    // owns the corner. The comparative views drop this chip straight into their
+    // own positioned box and want it anchored; `DisplayChrome` puts it in a corner
+    // the chrome itself anchors and shares with the display's control row, and an
+    // absolutely-positioned chip there sits *under* that row instead of above it
+    // — which is the collision this split fixes.
+    anchored: {
+        position: 'absolute',
+        bottom: 2,
+        right: 2,
+    },
+    bar: {
+        width: 120,
+    },
+}));
+/**
+ * Bottom-right progress chip for work running while usable content is already on
+ * screen: a refetch over stale geometry (dotplot, linear synteny), or a
+ * background job that is not a fetch at all (clustering, via `DisplayChrome`).
+ * It stays small and out of the way instead of masking the canvas the way the
+ * full loading overlay would, and surfaces the statusCallback message plus a
+ * determinate bar when the phase reports progress.
+ *
+ * Pure presentation — the caller owns the gate (its own `refetching` getter, or
+ * the chrome's "a status is set while the phase is ready") and the containing
+ * element owns the positioning context.
+ *
+ * It also owns the corner, unless `anchored={false}` says something else does.
+ * That escape exists because on the LGV side the corner is shared: the chrome
+ * anchors one box for both this and the display's control row, and a chip that
+ * pins itself lands *under* that row rather than above it.
+ */
+const ProgressChip = observer(function ProgressChip({ status, anchored = true, }) {
+    const { classes, cx } = useStyles();
+    return (_jsx("div", { className: cx(classes.root, anchored ? classes.anchored : undefined), "data-testid": "progress-chip", children: _jsx(LoadingProgress, { message: status.message, fraction: status.fraction, barClassName: classes.bar }) }));
+});
+export default ProgressChip;

package/esm/ui/RedErrorMessageBox.d.ts

@@ -1,3 +1,3 @@
 export default function RedErrorMessageBox({ children, }: {
     children: React.ReactNode;
-}): import("react/jsx-runtime").JSX.Element;
+}): import("react").JSX.Element;

package/esm/ui/RedErrorMessageBox.js

@@ -1,16 +1,22 @@
 import { jsx as _jsx } from "react/jsx-runtime";
-import { makeStyles } from "../util/tss-react/index.js";
+import { makeStyles } from '../util/tss-react/index.js';
 const useStyles = makeStyles()(theme => ({
     bg: {
         padding: 4,
         margin: 4,
         overflow: 'auto',
-        maxHeight: 200,
         background: theme.palette.mode === 'dark' ? '#833' : '#f88',
         border: `1px solid ${theme.palette.divider}`,
     },
 }));
+// The test-id, not the color, is what says "an error is on screen": this is the
+// box ErrorMessage and ErrorBanner both render into, and it is the one error
+// surface the website capture harness could not see. `ErrorBar` publishes
+// `reload_button` and `notifyError` publishes `snackbar-error`, so a capture
+// that still showed either failed loudly — but an MST type error surfacing here
+// over a view was captured and committed as if the figure were fine. Keying off
+// `#f88` instead would break on the dark theme and on any restyle.
 export default function RedErrorMessageBox({ children, }) {
     const { classes } = useStyles();
-    return _jsx("div", { className: classes.bg, children: children });
+    return (_jsx("div", { className: classes.bg, "data-testid": "error-message-box", children: children }));
 }

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

@@ -0,0 +1,5 @@
+import type { MenuItem } from '../Menu.tsx';
+export default function EndAdornment({ showHelp, menuItems, }: {
+    showHelp?: boolean;
+    menuItems?: MenuItem[];
+}): import("react").JSX.Element;

package/esm/ui/RefNameAutocomplete/EndAdornment.js

@@ -0,0 +1,31 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { Suspense, lazy, useState } from 'react';
+import Help from '@mui/icons-material/Help';
+import MoreVertIcon from '@mui/icons-material/MoreVert';
+import SearchIcon from '@mui/icons-material/Search';
+import { InputAdornment } from '@mui/material';
+import CascadingMenuButton from '../CascadingMenuButton.js';
+const HelpDialog = lazy(() => import('./HelpDialog.js'));
+// The search-box overflow (⋮) menu: consumer-supplied rows (e.g. recent
+// locations) sit above the built-in help entry. Rendered only when there is
+// something to show, so a bare box keeps just its search icon.
+export default function EndAdornment({ showHelp, menuItems = [], }) {
+    const [helpDialogOpen, setHelpDialogOpen] = useState(false);
+    const items = [
+        ...menuItems,
+        ...(showHelp
+            ? [
+                {
+                    label: 'Search box help',
+                    icon: Help,
+                    onClick: () => {
+                        setHelpDialogOpen(true);
+                    },
+                },
+            ]
+            : []),
+    ];
+    return (_jsxs(InputAdornment, { position: "end", style: { marginRight: 7 }, children: [_jsx(SearchIcon, { fontSize: "small" }), items.length ? (_jsx(CascadingMenuButton, { menuItems: items, size: "small", stopPropagation: true, tooltip: "Search box options", children: _jsx(MoreVertIcon, { fontSize: "small" }) })) : null, helpDialogOpen ? (_jsx(Suspense, { fallback: null, children: _jsx(HelpDialog, { handleClose: () => {
+                        setHelpDialogOpen(false);
+                    } }) })) : null] }));
+}

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

@@ -0,0 +1,3 @@
+export default function HelpDialog({ handleClose, }: {
+    handleClose: () => void;
+}): import("react").JSX.Element;

package/esm/ui/RefNameAutocomplete/HelpDialog.js

@@ -0,0 +1,7 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import InfoDialog from '../InfoDialog.js';
+export default function HelpDialog({ handleClose, }) {
+    return (_jsxs(InfoDialog, { open: true, maxWidth: "xl", onClose: () => {
+            handleClose();
+        }, title: "Using the search box", children: [_jsx("h3", { children: "Searching" }), _jsxs("ul", { children: [_jsx("li", { children: "Jump to a feature or reference sequence by typing its name in the location box and pressing Enter." }), _jsxs("li", { children: ["Jump to a specific region by typing the region into the location box as: ", _jsx("code", { children: "ref:start..end" }), " or ", _jsx("code", { children: "ref:start-end" }), ". Commas are allowed in the start and end coordinates. A space-separated list of locstrings can be used to open up multiple chromosomes at a time"] }), _jsxs("li", { children: ["Find a group of reference sequences by typing a pattern containing", ' ', _jsx("code", { children: "*" }), ", which stands for any run of characters. The matches appear in the dropdown, with a row at the top that opens all of them at once. Useful on a fragmented or haplotype-resolved assembly, where the useful selection is a pattern rather than a list you keep by hand."] })] }), _jsx("h3", { children: "Example Searches" }), _jsxs("ul", { children: [_jsxs("li", { children: [_jsx("code", { children: "BRCA" }), " - searches for the feature named BRCA"] }), _jsxs("li", { children: [_jsx("code", { children: "chr4" }), " - jumps to chromosome 4"] }), _jsxs("li", { children: [_jsx("code", { children: "chr4:79,500,000..80,000,000" }), " - jumps the region on chromosome 4 between 79.5Mb and 80Mb."] }), _jsxs("li", { children: [_jsx("code", { children: "chr1:1-100 chr2:1-100" }), " - create a split view of chr1:1-100 and chr2:1-100"] }), _jsxs("li", { children: [_jsx("code", { children: "chr1 chr2 chr3" }), " - open up multiple chromosomes at once"] }), _jsxs("li", { children: [_jsx("code", { children: "chr1:1-100[rev] chr2:1-100" }), " - open up the first region in the horizontally flipped orientation"] }), _jsxs("li", { children: [_jsx("code", { children: "chr1 100 200" }), " - use whitespace separated refname, start, end"] }), _jsxs("li", { children: [_jsx("code", { children: "*_hap1" }), " - list every reference sequence whose name ends in _hap1, and offer to open all of them"] })] })] }));
+}

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

@@ -0,0 +1,22 @@
+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[]>;
+    onSelect?: (region: BaseResult) => void;
+    onChange?: (val: string) => void;
+    minWidth?: number;
+    maxWidth?: number;
+    adornmentWidth?: number;
+    style?: CSSProperties;
+    endAdornment?: ReactNode;
+    helperText?: string;
+    inputStyle?: CSSProperties;
+}) => import("react").JSX.Element;
+export default RefNameAutocomplete;
+export { default as RefNameAutocompleteEndAdornment } from './EndAdornment.tsx';
+export { adornmentReservePx, getInputWidth } from './util.ts';

package/esm/ui/RefNameAutocomplete/index.js

@@ -0,0 +1,78 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { useState } from 'react';
+import { Autocomplete, TextField } from '@mui/material';
+import { observer } from 'mobx-react';
+import { useDebounce } from '../../util/hooks.js';
+import { useFetch } from '../../util/useFetch.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;
+    const externalValue = value ?? '';
+    // MUI Autocomplete tracks `inputValue` (displayed text) separately from
+    // `value` (selected item). We echo every MUI event into `inputValue` so
+    // external value changes, blur snap-back, and keystrokes all stay in sync.
+    const [inputValue, setInputValue] = useState(externalValue);
+    // `searchQuery` drives the fetch and filter — only updated on real typing
+    // so blur/reset events don't trigger phantom searches.
+    const [searchQuery, setSearchQuery] = useState('');
+    const debouncedSearch = useDebounce(searchQuery, 50);
+    const assembly = assemblyName ? assemblyManager.get(assemblyName) : undefined;
+    const shouldSearch = !!assemblyName && debouncedSearch !== '';
+    const { data: searchOptions, isLoading } = useFetch(
+    // `as const` so the key is a fixed-arity tuple: useFetch derives the
+    // fetcher's parameter list from it, and a plain array widens to a variadic
+    // the named parameters below cannot be destructured out of
+    shouldSearch
+        ? ['refNameSearch', assemblyName, debouncedSearch]
+        : null, async (_tag, _assembly, query, stopToken) => getDeduplicatedResult(await fetchResults(query, stopToken)), {
+        onError: e => {
+            session.notifyError(`${e}`, e);
+        },
+    });
+    const width = getInputWidth(externalValue, minWidth, maxWidth, adornmentWidth);
+    const hasSearchResults = !!searchOptions?.length;
+    return (_jsx(Autocomplete, { "data-testid": "autocomplete", disableListWrap: true, disableClearable: true, disabled: !assemblyName, freeSolo: true, includeInputInList: true, selectOnFocus: true, clearOnBlur: true, style: { ...style, width }, value: externalValue, loading: isLoading, inputValue: inputValue, onInputChange: (_event, newInputValue, reason) => {
+            setInputValue(newInputValue);
+            if (reason === 'input') {
+                setSearchQuery(newInputValue);
+                onChange?.(newInputValue);
+            }
+            else if (reason === 'blur' || reason === 'selectOption') {
+                // clear so stale results don't linger; skip 'reset' because MUI
+                // fires that during its own re-render loop and clearing it kills
+                // an in-flight search
+                setSearchQuery('');
+            }
+        }, loadingText: "loading results", onChange: (_event, selectedOption) => {
+            if (selectedOption) {
+                onSelect?.(coerceToResult(selectedOption));
+                // snap back to the current loc; if navigation succeeds the parent
+                // updates `value` and MUI's 'reset' event will reflect the new loc
+                setInputValue(externalValue);
+            }
+        }, 
+        // built inside the branch rather than every render: it scans the
+        // assembly's regions and materializes up to the cap in option objects,
+        // which is wasted work on the keystrokes that do have search results
+        options: hasSearchResults
+            ? searchOptions
+            : getRefNameOptions(assembly, searchQuery), getOptionDisabled: option => !!option.isLimit, 
+        // both sources arrive already matched against a query — searchOptions
+        // server-side for `debouncedSearch`, regionOptions live for `searchQuery`
+        // — so MUI must not re-filter them (its default filter would drop hits
+        // matching on a description rather than the display string). Only cap.
+        filterOptions: cap, renderInput: ({ slotProps: paramSlotProps, ...restParams }) => (_jsx(TextField, { ...restParams, variant: "outlined", size: "small", 
+            // override global theme default (margin="dense") whose asymmetric
+            // 8/4 top/bottom margins offset the input 2px downward
+            margin: "none", helperText: helperText, slotProps: {
+                ...paramSlotProps,
+                input: {
+                    ...paramSlotProps.input,
+                    style: inputStyle,
+                    ...(endAdornment !== undefined && { endAdornment }),
+                },
+            }, placeholder: "Search for location" })), getOptionLabel: getOptionLabel }));
+});
+export default RefNameAutocomplete;
+export { default as RefNameAutocompleteEndAdornment } from './EndAdornment.js';
+export { adornmentReservePx, getInputWidth } from './util.js';

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

@@ -0,0 +1,49 @@
+import BaseResult from '../../TextSearch/BaseResults.ts';
+import type { RefNameMatchSource } from '../../util/selectNamedRegions.ts';
+export interface Option {
+    isLimit?: boolean;
+    result: BaseResult;
+}
+export declare function cap(options: Option[]): Option[];
+/**
+ * The browse/pre-fetch fallback list, shown while a typed query is in flight and
+ * when it comes back empty (typed queries otherwise resolve through
+ * fetchResults).
+ *
+ * The matching itself is `matchRefNames`, in core beside the glob semantics,
+ * because Enter answers for the same typed text and the two must not each grow
+ * their own reading of it. What is left here is presentation: how many rows to
+ * materialize, and the bulk row.
+ *
+ * **AN EXACT REFNAME BEATS THE GLOB READING here too**, the rule
+ * `selectNamedRegions` states and `searchUtils` orders its glob branch after.
+ * `*` is a legal refName character and GRCh38's ALT decoys are HLA allele names,
+ * so `HLA-A*01:01:01:01` is a contig somebody typed in full — offering "Show all
+ * 4 regions matching HLA-A*01:01:01:01" above it is the box promising a set that
+ * Enter, on the same text, does not open. The individual matches still list: the
+ * pattern reading is not wrong, it is just not what leads.
+ *
+ * A glob may gather up to MAX_GLOB_REGIONS for that bulk row; a plain query
+ * never needs more than the visible list, so it keeps the tighter bound and the
+ * cost it always had. Collecting one past MAX_OPTIONS is what lets `cap` render
+ * its "keep typing" hint.
+ */
+export declare function getRefNameOptions(assembly: RefNameMatchSource | undefined, inputValue: string): Option[];
+export declare function getDeduplicatedResult(results: BaseResult[]): Option[];
+export declare function coerceToResult(option: string | Option): BaseResult;
+export declare function getOptionLabel(option: string | Option): string;
+/**
+ * What the end adornment occupies, and the number a caller passes as
+ * `adornmentWidth`.
+ *
+ * The ⋮ button is drawn for consumer-supplied rows as well as for the help one,
+ * so the reservation follows `menuItemCount || showHelp` — the same expression
+ * `EndAdornment` renders on. Both read it here rather than adding the constants
+ * up at the call site, which yields a box that has the button and is sized as
+ * if it did not.
+ */
+export declare function adornmentReservePx({ showHelp, menuItemCount, }: {
+    showHelp?: boolean;
+    menuItemCount?: number;
+}): number;
+export declare function getInputWidth(value: string, minWidth: number, maxWidth: number, adornmentWidth?: number): number;